The TypeScript MCP server template focuses on that path. It uses the official @modelcontextprotocol/sdk 1.x package, Zod, strict TypeScript, ESM, and Node.js 20 or newer. It includes two offline tools, a resource, stdio and Streamable HTTP entrypoints, and tests. You do not need credentials or a running database to try it.

Start with a small working loop

Clone the repository and run the checks:

git clone https://github.com/buildfound/mcp-server-template.git
cd mcp-server-template
npm install
npm run typecheck
npm run build
npm test
npm run inspect

The last command opens MCP Inspector against the compiled stdio entrypoint. List the tools, call add with {"a":2,"b":3}, and read info://server. This checks the same discovery and execution path that a client uses.

There are three boundaries to understand. Pure functions live under src/tools/. The createServer() factory in src/server.ts registers protocol capabilities. The entrypoints choose how messages reach that server. Keeping those boundaries visible makes it easier to replace the examples without changing transport code.

Register a tool with McpServer and Zod

The addition function in src/tools/add.ts is deliberately ordinary:

export function add(a: number, b: number): number {
  return a + b;
}

Inside createServer(), its registration looks like this:

server.registerTool(
  "add",
  {
    description: "Add two numbers.",
    inputSchema: { a: z.number(), b: z.number() },
    annotations: { readOnlyHint: true, openWorldHint: false },
  },
  ({ a, b }) => ({ content: [{ type: "text", text: String(add(a, b)) }] }),
);

The module imports McpServer from @modelcontextprotocol/sdk/server/mcp.js and z from zod. The SDK exposes the input schema to clients and validates tool arguments before invoking the handler. A caller passing a string for a receives a tool error.

The handler adapts a number into an MCP text response. Business logic does not need to know about content blocks, transports, or clients. Start new tools the same way: write a function, then give it a name, description, schema, and response adapter.

Return structured results for useful work

The second tool, word_stats, counts words and characters and returns the most frequent words. Try {"text":"Hello hello world!","top":1}. You get three words, eighteen characters, and hello with a count of two.

Its optional top argument defaults to five and accepts integers from one through twenty. The input text has a size limit. These constraints describe the function's useful operating range and keep accidental requests bounded.

The output schema in src/server.ts is:

outputSchema: {
  wordCount: z.number().int().nonnegative(),
  characterCount: z.number().int().nonnegative(),
  topWords: z.array(z.object({ word: z.string(), count: z.number().int().positive() })),
},

The registered handler returns both representations:

({ text, top }) => {
  const result = wordStats(text, top);
  return {
    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    structuredContent: { ...result },
  };
},

Clients can consume the structured object while still displaying readable text. The output schema gives that object a contract the SDK can validate.

Text counting needs explicit rules. Here, words are runs of Unicode letters and numbers, normalized to NFC and lowercased. Punctuation separates words. Frequency ties use JavaScript string order. Character count measures code points in the original input, including whitespace; it does not count visible grapheme clusters. Documenting those choices makes results interpretable.

Expose a resource

Resources give clients readable content at a URI. The template registers info://server with an application/json MIME type. Its callback returns this content block:

contents: [{
  uri: uri.href,
  mimeType: "application/json",
  text: JSON.stringify({ name, version, tools: ["add", "word_stats"] }, null, 2),
}],

The name and version come from package.json. The tools array describes the examples. When replacing them, update this array too. The URI is a protocol identifier; reading it does not make an HTTP request to a website.

Choose a transport

Use stdio when a local client launches your server as a child process. Run npm start after building, or npm run dev while editing. src/stdio.ts connects the factory to StdioServerTransport. Stdout carries MCP messages, so use console.error for diagnostics.

Use Streamable HTTP when the server should run separately from the client:

npm run start:http
curl http://127.0.0.1:3000/health

Clients connect to http://127.0.0.1:3000/mcp. HOST and PORT configure the listener. Each POST creates a fresh server and transport, with JSON responses and no session ID. This stateless choice avoids session storage but provides no persistent notification stream or resumability. GET and DELETE on /mcp return 405.

The default listener binds to loopback. Host validation helps address DNS rebinding, and requests with a cross-origin Origin header are rejected. Authentication is not included. Before network deployment, add access controls, TLS, request limits, and a trusted host/origin policy appropriate to your proxy.

Connect Claude

For Claude Desktop, open Settings, then Developer, then Edit Config. Merge this into claude_desktop_config.json and restart the application:

{
  "mcpServers": {
    "template": {
      "command": "node",
      "args": ["/absolute/path/mcp-server-template/dist/stdio.js"]
    }
  }
}

Replace the path with your compiled checkout. If the application cannot locate Node, give command its absolute executable path. The local server guide explains the configuration file.

For Claude Code, choose either command from its MCP setup documentation:

claude mcp add --transport stdio template -- node /absolute/path/mcp-server-template/dist/stdio.js
claude mcp add --transport http template-http http://127.0.0.1:3000/mcp

Start the HTTP server separately for the second command. Check the connection with /mcp inside Claude Code.

Test through the protocol

Unit tests cover the functions, while test/server.test.ts connects a real SDK client without sockets:

const server = createServer();
const client = new Client({ name: "test-client", version: "1.0.0" });
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
t.after(async () => { await client.close(); await server.close(); });
await server.connect(serverTransport);
await client.connect(clientTransport);

This excerpt runs inside a node:test callback. The test then lists tools and resources, calls both tools, checks structured output, reads the resource, and exercises invalid inputs. Another integration test uses an ephemeral HTTP port and StreamableHTTPClientTransport. Together they check registration and transport behavior beyond the pure calculations.

Make it your own

Fork the repository, rename the package and bin, replace the example functions, and update resource metadata. Run npm install after renaming to refresh the lockfile, then typecheck, build, and test. Keep the MIT notice. Rebuild before restarting clients that point to dist/stdio.js.

Built by BuildFound, a founder-led AI product studio.

This post builds a small Node.js script that finds that second list. You give it a handful of keywords. It pulls the top results for each, works out which apps keep appearing and how high, and writes a CSV you can sort in any spreadsheet. No dependencies, no API key, about 100 lines.

Then we go through the walls you hit when you try to trust the output.

Everything here was run on Node 20 against the live iTunes Search API while writing.

The idea in one paragraph

For each keyword, take the top N apps (default 10). For each app, record its position per keyword. Then score each app two ways:

• Coverage: the share of your keywords where it's in the top N. "How often is this app in my way?"
• Weighted score: the mean of 1 / position across your keywords (reciprocal rank). A #1 counts as 1.0, a #10 as 0.1, and an absence as 0. "How much is it in my way?"

Coverage alone overrates apps that sit at #9 everywhere. Reciprocal rank alone overrates an app that owns one keyword. Looking at both side by side is what makes the table useful.

The script

Save as overlap.mjs:

// Who actually competes with you in App Store search? Node 20+, no dependencies.
// Usage: node overlap.mjs "calorie tracker" "calorie counter" "macro tracker" ...
import { writeFile } from "node:fs/promises";

const COUNTRY = process.env.COUNTRY ?? "us";
const TOP_N = Number(process.env.TOP_N ?? 10);
const DELAY_MS = 3500; // ~17 requests/min, below Apple's ~20/min guidance

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function search(term, attempt = 0) {
  const url = new URL("https://itunes.apple.com/search");
  url.search = new URLSearchParams({
    term, country: COUNTRY, entity: "software", limit: "50",
  });
  const res = await fetch(url, {
    headers: { "User-Agent": "overlap-script/0.1 (you@example.com)" },
    signal: AbortSignal.timeout(20_000),
  });
  if ([403, 429, 500, 502, 503].includes(res.status) && attempt < 4) {
    const wait = 2 ** attempt * 10_000 + Math.random() * 5_000;
    console.error(`  ${res.status} on "${term}", retrying in ${Math.round(wait / 1000)}s`);
    await sleep(wait);
    return search(term, attempt + 1);
  }
  if (!res.ok) throw new Error(`${res.status} for "${term}"`);
  // Content-Type is often text/javascript, so don't rely on res.json() sniffing.
  const body = JSON.parse(await res.text());
  return body.results.slice(0, TOP_N);
}

const keywords = process.argv.slice(2);
if (keywords.length < 2) {
  console.error('Give me at least two keywords, e.g. node overlap.mjs "habit tracker" "daily planner"');
  process.exit(1);
}

// appId -> { name, seller, ratings, hits: Map<keyword, position> }
const apps = new Map();

for (const [i, kw] of keywords.entries()) {
  if (i > 0) await sleep(DELAY_MS);
  const results = await search(kw);
  results.forEach((r, idx) => {
    const app = apps.get(r.trackId) ?? {
      name: r.trackName, seller: r.sellerName,
      ratings: r.userRatingCount ?? 0, hits: new Map(),
    };
    app.hits.set(kw, idx + 1);
    apps.set(r.trackId, app);
  });
  console.error(`fetched "${kw}" (${results.length} results)`);
}

// Score: share of keywords where the app is top-N, plus a position-weighted
// score so #1 counts more than #10 (reciprocal rank, normalised to 0-1).
const rows = [...apps.entries()].map(([id, a]) => {
  const rr = [...a.hits.values()].reduce((s, p) => s + 1 / p, 0);
  return {
    id, name: a.name, seller: a.seller, ratings: a.ratings,
    coverage: a.hits.size / keywords.length,
    weighted: rr / keywords.length,
    positions: keywords.map((k) => a.hits.get(k) ?? ""),
  };
}).sort((x, y) => y.weighted - x.weighted || y.coverage - x.coverage);

console.log(`\nTop competitors across ${keywords.length} keywords (${COUNTRY}, top ${TOP_N}):\n`);
console.table(rows.slice(0, 12).map((r) => ({
  app: r.name.slice(0, 32),
  coverage: `${Math.round(r.coverage * 100)}%`,
  weighted: r.weighted.toFixed(2),
  ratings: r.ratings,
})));

const esc = (v) => `"${String(v).replaceAll('"', '""')}"`;
const csv = [
  ["app_id", "name", "seller", "ratings", "coverage", "weighted", ...keywords].map(esc).join(","),
  ...rows.map((r) => [r.id, r.name, r.seller, r.ratings,
    r.coverage.toFixed(2), r.weighted.toFixed(3), ...r.positions].map(esc).join(",")),
].join("\n");
await writeFile(`overlap-${COUNTRY}.csv`, csv + "\n");
console.log(`\nWrote overlap-${COUNTRY}.csv (${rows.length} apps)`);

Notes on the choices:

• Sequential, with a fixed delay. Promise.all over 30 keywords is the fastest way to get your IP throttled (see wall 1). A plain for…of with await sleep() is boring and correct.
• AbortSignal.timeout is built into Node 18+, so you don't need a timeout library.
• JSON.parse(await res.text()): the API sends content-type: text/javascript, so parse the text yourself instead of trusting a content-type check.
• Keyed on trackId. Names change. Ids don't.

Running it

Say you're building a planner app:

node overlap.mjs "habit tracker" "daily planner" "routine planner" "to do list" "adhd planner"

Output from my run (US storefront, trimmed):

Top competitors across 5 keywords (us, top 10):

app                              coverage  weighted  ratings
'Structured: Daily Planner Todo' '80%'     '0.65'    167714
'Habit Tracker'                  '80%'     '0.37'    148017
'To Do List MinimaList & Widget' '60%'     '0.24'    48420
'Daily Planner, To-Do List'      '60%'     '0.18'    11583
'Routine Planner, Habit Tracker' '60%'     '0.16'    18074
'Finch: Self-Care Pet'           '60%'     '0.13'    764903
'Todoist: To Do List & Calendar' '20%'     '0.10'    129909

Wrote overlap-us.csv (34 apps)

That table already holds a few non-obvious things. Finch, a self-care pet app, shows up in 60% of these "planner" searches, which no planner developer would have listed as a rival. Todoist, the famous one, appears in only one of the five. Open overlap-us.csv and the per-keyword position columns show where each rival is strong. That's the start of a keyword strategy: phrases where the top apps have few ratings and no rival covers everything are worth a closer look.

Run it for another storefront with COUNTRY=gb node overlap.mjs ..., or widen the net with TOP_N=25.

Wall 1: Rate limits

Apple describes the Search API limit as roughly 20 calls per minute, subject to change, and answers excess traffic with 403s. The script waits 3.5 s between calls and backs off exponentially on 403/429/5xx. That makes 40 keywords take about 2.5 minutes. Fine for a script, wrong for an HTTP handler. If you put this behind a UI, run it as a background job and cache the results by day.

Wall 2: The API is not the App Store search box

The iTunes Search API searches the catalogue. Apple doesn't promise its ordering matches what someone sees in the App Store app, where an ad slot, editorial content and other undocumented factors can come into play. Treat the positions as a consistent relative signal: good for "who keeps showing up", weaker for "we're exactly #4". Check a few keywords by hand on a device before you make decisions from them.

Wall 3: Your keyword list is the biggest bias in the output

The matrix only knows the keywords you fed it. Pick five keywords that describe your positioning and you'll mostly find apps that copy your positioning. To get a fairer picture:

• Mix head terms ("to do list") with long-tail phrases ("adhd planner").
• Include a few rival brand names. People search for those, and the results show who sits next to the leader.
• Use 20 to 40 keywords, not 5. With 5, one keyword is 20% of the coverage score.

Wall 4: One developer, many apps

Studios often ship several near-identical apps, and each takes its own row. The CSV includes seller so you can group by developer in a pivot table. A seller with four apps at 20% coverage each may matter more than a single app at 60%.

Wall 5: Ratings are not size

It's tempting to sort by userRatingCount and call that market share. Don't. Rating counts build up over an app's whole life, depend on how hard an app prompts for reviews, and say nothing about this month. An old app with 700k ratings can be coasting while a newer one with 2k ratings grows fast. Use ratings as a rough "how established is page one" signal, nothing more.

Wall 6: Scraping, bot protection and terms

When the Search API's ceilings annoy you (200 results max, one storefront per call), you'll be tempted to scrape the App Store web pages or the private endpoints the App Store app uses. Those are undocumented, protected against bots and liable to change overnight, and using them may break Apple's terms. Read the Search API terms as well before shipping anything commercial. Build on the public endpoint and accept its limits.

What search overlap can't tell you

This script answers "who do I keep running into in search?" It says nothing about how those competitors get users outside search: which ads they keep paying for, and which posts about them took off.

For that part I don't write scripts. I use PeekPanda*. It keeps dated public paid-ad observations for iOS apps, millions of ads in total, so you can see which creatives a rival has kept running for months, next to the searches it's been observed in. An ad nobody switches off for months is usually the one worth studying. I still run this overlap script first, because it's free, quick and shows me which apps are worth looking up.

Wrap-up

• About 100 lines of dependency-free Node turns a keyword list into a ranked competitor map plus a CSV.
• Score with both coverage and reciprocal rank, key on trackId, and group by seller.
• Respect the rate limit, treat positions as relative, and remember the output is only as good as your keyword list.

Run it on your own niche. The app you least expected near the top of the table is usually the most useful thing it tells you.

*I build it.