@amitshrivastava/create-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# create-mcp-server
+
+```bash
+npm create @amitshrivastava/mcp-server@latest my-server
+```
+
+Scaffold a production-ready **Model Context Protocol** server in 30 seconds. Pick a template, answer two questions, get a runnable server with a Claude Desktop config snippet ready to paste.
+
+Built by [Amit Shrivastava](https://www.ashrivastava.xyz), creator of the [portfolio-mcp](https://github.com/amitshrivastavaa/amit-shrivastava/tree/main/mcp-server) server. Companion to the [MCP Inspector demo](https://www.ashrivastava.xyz/ai-labs/mcp-inspector).
+
+## What it generates
+
+Each template is a complete, runnable TypeScript MCP server:
+
+- `package.json` with the right `@modelcontextprotocol/sdk` version pinned
+- `tsconfig.json` set up for stdio MCP servers (ES2022, Bundler resolution)
+- `src/index.ts` — the server, with at least one working tool
+- `README.md` explaining the server and how to wire it up
+- `.gitignore`
+
+Build with `npm run build`, point Claude Desktop / Cursor / Cline at `dist/index.js`, and it works.
+
+## Templates
+
+| Template | What it gives you |
+|---|---|
+| **`blank`** | A minimal MCP server with a single example tool (`greet`). Best when you want to add custom tools by hand. |
+| **`markdown-rag`** | An MCP server that exposes a `./content/` directory of markdown files as resources, with a keyword `search` tool. Drop your own docs in and it serves them. |
+
+## Usage
+
+```bash
+npm create @amitshrivastava/mcp-server@latest
+
+# or with a name + non-interactive
+npm create @amitshrivastava/mcp-server@latest my-server
+
+# equivalent
+npx @amitshrivastava/create-mcp-server my-server
+```
+
+You'll be prompted for:
+
+- **Project name** — any valid directory name
+- **Template** — see the table above
+- **Description** — written into `package.json`
+- **Author** — written into `package.json`
+
+After scaffolding it prints a complete Claude Desktop config snippet with the absolute path to your built `dist/index.js`.
+
+## What MCP is
+
+The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard from Anthropic that lets any AI client talk to any tool, database, or service through one protocol. Instead of building custom integrations for Claude Desktop, Cursor, and every other client, you build one MCP server and they all consume it.
+
+This CLI gets you from zero to "my server is plugged into Claude Desktop" in about a minute.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// create-mcp-server — interactive scaffolder for Model Context Protocol servers.
+//
+// Usage:
+//   npm create @amitshrivastava/mcp-server@latest [project-name]
+//   # or
+//   npx @amitshrivastava/create-mcp-server [project-name]
+//
+// Reads templates from ./templates/<name>/, copies into ./<project-name>/,
+// substitutes __NAME__ / __DESCRIPTION__ / __AUTHOR__ placeholders, prints
+// next-step instructions including a Claude Desktop config snippet.
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import readline from "node:readline/promises";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATES_DIR = join(__dirname, "..", "templates");
+// ─── tiny terminal helpers ─────────────────────────────────────────────────────
+const SUPPORTS_COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = {
+    bold: (s) => (SUPPORTS_COLOR ? `\x1b[1m${s}\x1b[22m` : s),
+    dim: (s) => (SUPPORTS_COLOR ? `\x1b[2m${s}\x1b[22m` : s),
+    cyan: (s) => (SUPPORTS_COLOR ? `\x1b[36m${s}\x1b[39m` : s),
+    green: (s) => (SUPPORTS_COLOR ? `\x1b[32m${s}\x1b[39m` : s),
+    red: (s) => (SUPPORTS_COLOR ? `\x1b[31m${s}\x1b[39m` : s),
+};
+function die(message) {
+    console.error(c.red("✗ " + message));
+    process.exit(1);
+}
+// ─── main ──────────────────────────────────────────────────────────────────────
+async function main() {
+    const argName = process.argv[2];
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    console.log("");
+    console.log(c.bold("🔌 create-mcp-server"));
+    console.log(c.dim("   Scaffold a Model Context Protocol server in 30 seconds.\n"));
+    const name = await ask(rl, "Project name:", argName || "my-mcp-server");
+    if (!/^[a-z0-9_-]+$/i.test(name)) {
+        rl.close();
+        die("Project name must contain only letters, digits, hyphens, and underscores.");
+    }
+    const templates = readdirSync(TEMPLATES_DIR).filter((d) => statSync(join(TEMPLATES_DIR, d)).isDirectory());
+    if (templates.length === 0) {
+        rl.close();
+        die("No templates found. Did you install the package correctly?");
+    }
+    console.log("\n" + c.bold("Templates:"));
+    templates.forEach((t, i) => {
+        const meta = readTemplateMeta(join(TEMPLATES_DIR, t));
+        console.log(`  ${c.cyan(String(i + 1))}. ${c.bold(t)}${meta ? c.dim(" — " + meta) : ""}`);
+    });
+    const choice = (await ask(rl, "\nTemplate number:", "1")).trim();
+    const tIdx = parseInt(choice, 10) - 1;
+    if (Number.isNaN(tIdx) || tIdx < 0 || tIdx >= templates.length) {
+        rl.close();
+        die(`Invalid template choice. Pick 1..${templates.length}.`);
+    }
+    const template = templates[tIdx];
+    const description = await ask(rl, "Description:", `MCP server: ${name}`);
+    const author = await ask(rl, "Author:", "");
+    rl.close();
+    const targetDir = join(process.cwd(), name);
+    if (existsSync(targetDir)) {
+        die(`Target directory ${name} already exists.`);
+    }
+    const answers = { name, template, description, author };
+    copyTemplate(join(TEMPLATES_DIR, template), targetDir, answers);
+    printSummary(targetDir, answers);
+}
+async function ask(rl, q, def) {
+    const prompt = def ? `${q} ${c.dim("(" + def + ")")} ` : `${q} `;
+    const a = (await rl.question(prompt)).trim();
+    return a || def;
+}
+function readTemplateMeta(dir) {
+    const meta = join(dir, "TEMPLATE.md");
+    if (!existsSync(meta))
+        return null;
+    return readFileSync(meta, "utf-8").trim().split("\n")[0];
+}
+function copyTemplate(src, dest, answers) {
+    mkdirSync(dest, { recursive: true });
+    for (const entry of readdirSync(src)) {
+        const srcPath = join(src, entry);
+        // npm strips real `.gitignore` files from published packages; the template
+        // ships it as `_gitignore` and we rename on copy.
+        const renamed = entry === "_gitignore" ? ".gitignore" : entry;
+        if (renamed === "TEMPLATE.md")
+            continue;
+        const destPath = join(dest, renamed);
+        const stat = statSync(srcPath);
+        if (stat.isDirectory()) {
+            copyTemplate(srcPath, destPath, answers);
+        }
+        else {
+            const raw = readFileSync(srcPath, "utf-8");
+            writeFileSync(destPath, substitute(raw, answers));
+        }
+    }
+}
+function substitute(text, answers) {
+    return text
+        .replace(/__NAME__/g, answers.name)
+        .replace(/__DESCRIPTION__/g, answers.description)
+        .replace(/__AUTHOR__/g, answers.author || "")
+        .replace(/__TEMPLATE__/g, answers.template);
+}
+function printSummary(dir, answers) {
+    console.log("");
+    console.log(c.green("✓") + " Scaffolded " + c.bold(answers.name) + c.dim(` (${answers.template})`));
+    console.log(c.dim("  at " + dir));
+    console.log("");
+    console.log(c.bold("Next steps:"));
+    console.log("  " + c.cyan("cd " + answers.name));
+    console.log("  " + c.cyan("npm install"));
+    console.log("  " + c.cyan("npm run build"));
+    console.log("");
+    console.log(c.bold("Then add to your MCP client (e.g. Claude Desktop):"));
+    console.log(c.dim("  ~/Library/Application Support/Claude/claude_desktop_config.json"));
+    console.log("");
+    console.log("  {");
+    console.log('    "mcpServers": {');
+    console.log(`      ${c.cyan(`"${answers.name}"`)}: {`);
+    console.log('        "command": "node",');
+    console.log(`        "args": [${c.cyan(`"${dir}/dist/index.js"`)}]`);
+    console.log("      }");
+    console.log("    }");
+    console.log("  }");
+    console.log("");
+    console.log("Restart Claude Desktop. See " + c.bold(answers.name + "/README.md") + " for details.");
+    console.log("");
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@amitshrivastava/create-mcp-server",
+  "version": "0.1.0",
+  "description": "Scaffold a production-ready Model Context Protocol (MCP) server in 30 seconds. Pick a template, answer two questions, get a runnable server.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "create-mcp-server": "./dist/index.js"
+  },
+  "files": ["dist", "templates", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "keywords": ["mcp", "model-context-protocol", "anthropic", "claude", "scaffold", "cli", "ai", "agent"],
+  "author": "Amit Shrivastava",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amitshrivastavaa/amit-shrivastava.git",
+    "directory": "create-mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/amitshrivastavaa/amit-shrivastava/issues"
+  },
+  "homepage": "https://github.com/amitshrivastavaa/amit-shrivastava/tree/main/create-mcp-server#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4.19.0",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/blank/README.md

@@ -0,0 +1,69 @@
+# __NAME__
+
+__DESCRIPTION__
+
+A Model Context Protocol server, scaffolded by [`create-mcp-server`](https://github.com/amitshrivastavaa/amit-shrivastava/tree/main/create-mcp-server).
+
+## Install
+
+```bash
+npm install
+npm run build
+```
+
+## Wire it into Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (or the equivalent on your OS):
+
+```json
+{
+  "mcpServers": {
+    "__NAME__": {
+      "command": "node",
+      "args": ["/absolute/path/to/__NAME__/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see `__NAME__` in the MCP menu (the plug icon).
+
+## Try it
+
+In Claude Desktop:
+
+> Use __NAME__ to greet Sara
+
+The client will call the `greet` tool and you'll see the response inline.
+
+## Add your own tools
+
+Open `src/index.ts`. The `ListToolsRequestSchema` handler returns your tool catalog; the `CallToolRequestSchema` handler dispatches to the right implementation.
+
+Pattern:
+
+```ts
+// in ListToolsRequestSchema
+{
+  name: "my_tool",
+  description: "What the tool does",
+  inputSchema: {
+    type: "object",
+    properties: { input: { type: "string" } },
+    required: ["input"],
+  },
+}
+
+// in CallToolRequestSchema
+if (name === "my_tool") {
+  const input = String(args.input || "")
+  const result = await doSomething(input)
+  return { content: [{ type: "text", text: result }] }
+}
+```
+
+After changing tools, run `npm run build` and restart Claude Desktop.
+
+## License
+
+MIT

package/templates/blank/TEMPLATE.md

@@ -0,0 +1 @@
+Minimal MCP server. One example tool. Build your own from here.

package/templates/blank/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+*.tsbuildinfo

package/templates/blank/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "__NAME__",
+  "version": "0.1.0",
+  "description": "__DESCRIPTION__",
+  "author": "__AUTHOR__",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "__NAME__": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4.19.0",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/blank/src/index.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// __NAME__ — MCP server. Generated by create-mcp-server.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js"
+
+const server = new Server(
+  { name: "__NAME__", version: "0.1.0" },
+  { capabilities: { tools: {} } },
+)
+
+// ─── Tools ────────────────────────────────────────────────────────────────────
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "greet",
+      description: "Say hello to someone.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Who to greet" },
+        },
+        required: ["name"],
+      },
+    },
+    // Add your tools here.
+  ],
+}))
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: rawArgs } = request.params
+  const args = (rawArgs ?? {}) as Record<string, unknown>
+
+  if (name === "greet") {
+    const who = String(args.name || "world")
+    return { content: [{ type: "text", text: `Hello, ${who}!` }] }
+  }
+
+  throw new Error(`Unknown tool: ${name}`)
+})
+
+// ─── Boot ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  // stderr — stdout is reserved for the JSON-RPC stdio transport.
+  console.error("__NAME__: ready")
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+}
+
+main().catch((err) => {
+  console.error("__NAME__ failed to start:", err)
+  process.exit(1)
+})

package/templates/blank/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/markdown-rag/README.md

@@ -0,0 +1,83 @@
+# __NAME__
+
+__DESCRIPTION__
+
+A markdown-RAG Model Context Protocol server, scaffolded by [`create-mcp-server`](https://github.com/amitshrivastavaa/amit-shrivastava/tree/main/create-mcp-server). Exposes every `.md` file in `./content/` as an MCP resource plus a keyword `search` tool.
+
+## Install
+
+```bash
+npm install
+npm run build
+```
+
+## Add your content
+
+Drop `.md` files into `./content/`. Each file becomes a resource at `doc://<filename-without-md>`. Frontmatter is optional but recommended:
+
+```md
+---
+title: My Doc
+description: One-line summary used in search results.
+---
+
+# My Doc
+
+Body markdown here...
+```
+
+You can also point at a different content directory:
+
+```bash
+MCP_CONTENT_DIR=/abs/path/to/docs npm start
+```
+
+## Wire it into Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "__NAME__": {
+      "command": "node",
+      "args": ["/absolute/path/to/__NAME__/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see `__NAME__` in the MCP menu.
+
+## What it exposes
+
+**Resources** (one per markdown file):
+
+- `doc://<slug>` — full markdown content with frontmatter
+
+**Tools**:
+
+- `search(query, limit?)` — keyword-ranked search across titles, descriptions, and body
+- `list()` — every doc with title + slug
+
+## Try it
+
+In Claude Desktop:
+
+> Use __NAME__ to search for "introduction"
+
+Claude will call `search`, then read the top hits via their `doc://` URIs and summarize.
+
+## Going beyond keyword search
+
+When keyword search isn't enough, swap it for embeddings:
+
+1. Add `@huggingface/transformers` to `dependencies`.
+2. At startup, embed each doc's body with `all-MiniLM-L6-v2`.
+3. In `search`, embed the query and rank docs by cosine similarity (dot product on normalised vectors).
+
+The portfolio-mcp server in the parent repo uses this pattern — see [its source](https://github.com/amitshrivastavaa/amit-shrivastava/tree/main/mcp-server) for a working example.
+
+## License
+
+MIT

package/templates/markdown-rag/TEMPLATE.md

@@ -0,0 +1 @@
+Markdown RAG: exposes a ./content/*.md directory as resources + a keyword search tool.

package/templates/markdown-rag/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+*.tsbuildinfo

package/templates/markdown-rag/content/example.md

@@ -0,0 +1,16 @@
+---
+title: Example Doc
+description: Replace this file with your own markdown. Anything in ./content/ becomes a queryable MCP resource.
+---
+
+# Hello from create-mcp-server
+
+This file demonstrates how the `markdown-rag` template exposes content.
+
+You can:
+
+- Add as many `.md` files as you want to this `./content/` directory.
+- Use frontmatter (`title`, `description`) to make search results nicer.
+- Query them from Claude Desktop with prompts like *"Use __NAME__ to search for hello"*.
+
+When you're ready to graduate beyond keyword search, the README explains how to swap in vector embeddings.

package/templates/markdown-rag/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "__NAME__",
+  "version": "0.1.0",
+  "description": "__DESCRIPTION__",
+  "author": "__AUTHOR__",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "__NAME__": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "gray-matter": "^4.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4.19.0",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/markdown-rag/src/index.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// __NAME__ — markdown-RAG MCP server. Generated by create-mcp-server.
+//
+// Exposes every .md file in ./content/ as an MCP resource (uri = doc://<slug>)
+// and provides a keyword `search` tool that ranks docs by term-overlap against
+// title + description + body. No embedding model — keep it lean. Replace the
+// scorer with cosine-over-embeddings if you outgrow keyword search.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js"
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import matter from "gray-matter"
+
+interface Doc {
+  slug: string
+  title: string
+  description: string
+  content: string
+}
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// Candidate content directories, in priority order. Override with MCP_CONTENT_DIR.
+function findContentDir(): string {
+  const candidates = [
+    process.env.MCP_CONTENT_DIR,
+    join(__dirname, "..", "content"),
+    join(__dirname, "..", "..", "content"),
+  ].filter((c): c is string => typeof c === "string" && c.length > 0)
+  for (const dir of candidates) {
+    if (existsSync(dir)) return dir
+  }
+  throw new Error(
+    "Could not find content directory. Create ./content/*.md or set MCP_CONTENT_DIR to an absolute path.",
+  )
+}
+
+function loadDocs(): Doc[] {
+  const dir = findContentDir()
+  const files = readdirSync(dir).filter((f) => f.endsWith(".md"))
+  return files.map((file) => {
+    const slug = file.replace(/\.md$/, "")
+    const raw = readFileSync(join(dir, file), "utf-8")
+    const { data, content } = matter(raw)
+    return {
+      slug,
+      title: typeof data.title === "string" ? data.title : slug,
+      description: typeof data.description === "string" ? data.description : "",
+      content,
+    }
+  })
+}
+
+let DOCS: Doc[] = []
+
+const server = new Server(
+  { name: "__NAME__", version: "0.1.0" },
+  { capabilities: { resources: {}, tools: {} } },
+)
+
+// ─── Resources ────────────────────────────────────────────────────────────────
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: DOCS.map((d) => ({
+    uri: `doc://${d.slug}`,
+    name: d.title,
+    description: d.description,
+    mimeType: "text/markdown",
+  })),
+}))
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const uri = request.params.uri
+  const match = uri.match(/^doc:\/\/(.+)$/)
+  if (!match) throw new Error(`Unknown resource URI: ${uri}`)
+  const slug = match[1]
+  const doc = DOCS.find((d) => d.slug === slug)
+  if (!doc) throw new Error(`Doc not found: ${slug}`)
+  const text = [
+    "---",
+    `title: ${doc.title}`,
+    doc.description ? `description: ${doc.description}` : null,
+    "---",
+    "",
+    doc.content,
+  ]
+    .filter((l): l is string => l !== null)
+    .join("\n")
+  return { contents: [{ uri, mimeType: "text/markdown", text }] }
+})
+
+// ─── Tools ────────────────────────────────────────────────────────────────────
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "search",
+      description: "Keyword search across all docs. Returns ranked results with doc:// URIs to read in full.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Keywords to search for" },
+          limit: { type: "number", description: "Max results (default 5, max 20)" },
+        },
+        required: ["query"],
+      },
+    },
+    {
+      name: "list",
+      description: "List every doc with title and slug.",
+      inputSchema: { type: "object", properties: {} },
+    },
+  ],
+}))
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: rawArgs } = request.params
+  const args = (rawArgs ?? {}) as Record<string, unknown>
+
+  if (name === "list") {
+    const text = DOCS.map((d) => `- ${d.title} [${d.slug}] — ${d.description}`).join("\n")
+    return { content: [{ type: "text", text: `${DOCS.length} docs:\n\n${text}` }] }
+  }
+
+  if (name === "search") {
+    const query = String(args.query || "").toLowerCase().trim()
+    const limit = Math.min(Math.max(1, Number(args.limit) || 5), 20)
+    if (!query) {
+      return { content: [{ type: "text", text: "Provide a non-empty `query`." }], isError: true }
+    }
+    const terms = query.split(/\s+/).filter(Boolean)
+    const scored = DOCS.map((d) => {
+      const text = `${d.title} ${d.description} ${d.content}`.toLowerCase()
+      const score = terms.reduce((s, t) => (text.includes(t) ? s + 1 : s), 0)
+      return { d, score }
+    })
+      .filter((x) => x.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit)
+    if (scored.length === 0) {
+      return { content: [{ type: "text", text: `No docs matched "${query}".` }] }
+    }
+    const lines = scored.map(({ d, score }) =>
+      `- [score ${score}] ${d.title} — doc://${d.slug}\n  ${d.description}`,
+    )
+    return { content: [{ type: "text", text: `Top ${scored.length} matches for "${query}":\n\n${lines.join("\n\n")}` }] }
+  }
+
+  throw new Error(`Unknown tool: ${name}`)
+})
+
+// ─── Boot ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  DOCS = loadDocs()
+  console.error(`__NAME__: loaded ${DOCS.length} docs`)
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+}
+
+main().catch((err) => {
+  console.error("__NAME__ failed to start:", err)
+  process.exit(1)
+})

package/templates/markdown-rag/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}