@nexus-lab/create-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# create-mcp-server
+
+Scaffold a new [Model Context Protocol](https://modelcontextprotocol.io/) server in seconds.
+
+```bash
+npm create mcp-server my-server
+```
+
+## Features
+
+- **TypeScript + ESM** — Modern setup out of the box
+- **Secure defaults** — Zod schema validation for all inputs
+- **Multiple templates** — Choose what fits your use case
+- **Test-ready** — Vitest included in the `full` template
+- **Zero config** — Works immediately after generation
+
+## Templates
+
+### `minimal`
+The simplest possible MCP server. One tool, stdio transport.
+
+```bash
+npm create mcp-server my-server -- --template minimal
+```
+
+### `full`
+Tools, resources, prompts, and testing all wired up.
+
+```bash
+npm create mcp-server my-server -- --template full
+```
+
+### `http`
+Streamable HTTP transport with Express. Ready for remote deployment.
+
+```bash
+npm create mcp-server my-server -- --template http
+```
+
+## Usage
+
+```bash
+# Interactive mode
+npm create mcp-server
+
+# With project name
+npm create mcp-server my-server
+
+# With template
+npm create mcp-server my-server -- --template full
+
+# Skip npm install
+npm create mcp-server my-server -- --no-install
+
+# Skip git init
+npm create mcp-server my-server -- --no-git
+```
+
+## What you get
+
+```
+my-server/
+├── src/
+│   └── index.ts        # Server entry point
+├── package.json
+├── tsconfig.json
+└── .gitignore
+```
+
+The `full` template also includes:
+```
+├── src/
+│   ├── index.ts        # Server entry point
+│   ├── tools.ts        # Tool definitions
+│   ├── resources.ts    # Resource definitions
+│   └── prompts.ts      # Prompt definitions
+├── tests/
+│   └── tools.test.ts   # Example tests
+└── vitest.config.ts
+```
+
+## After scaffolding
+
+```bash
+cd my-server
+npm run build
+node dist/index.js
+```
+
+To use with Claude Code, add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "node",
+      "args": ["/path/to/my-server/dist/index.js"]
+    }
+  }
+}
+```
+
+## License
+
+MIT — [Nexus Lab](https://github.com/nexus-lab)

package/dist/generator.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectConfig } from "./prompts.js";
+export declare function generateProject(config: ProjectConfig): Promise<void>;

package/dist/generator.js

@@ -0,0 +1,61 @@
+import path from "node:path";
+import fs from "fs-extra";
+import chalk from "chalk";
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+function getTemplatesDir() {
+    // In development: src/templates, in production: dist/../templates
+    const devPath = path.resolve(__dirname, "..", "templates");
+    const srcPath = path.resolve(__dirname, "templates");
+    return fs.existsSync(devPath) ? devPath : srcPath;
+}
+export async function generateProject(config) {
+    const targetDir = path.resolve(process.cwd(), config.projectName);
+    if (await fs.pathExists(targetDir)) {
+        const files = await fs.readdir(targetDir);
+        if (files.length > 0) {
+            throw new Error(`Directory "${config.projectName}" already exists and is not empty`);
+        }
+    }
+    console.log(chalk.dim(`  Creating project in ${targetDir}...`));
+    // Copy template
+    const templatesDir = getTemplatesDir();
+    const templateDir = path.join(templatesDir, config.template);
+    if (!(await fs.pathExists(templateDir))) {
+        throw new Error(`Template "${config.template}" not found at ${templateDir}`);
+    }
+    await fs.copy(templateDir, targetDir);
+    // Update package.json with user config
+    const pkgPath = path.join(targetDir, "package.json");
+    const pkg = await fs.readJson(pkgPath);
+    pkg.name = config.projectName;
+    pkg.description = config.description;
+    await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+    // Rename _gitignore to .gitignore (npm strips .gitignore from packages)
+    const gitignoreSrc = path.join(targetDir, "_gitignore");
+    if (await fs.pathExists(gitignoreSrc)) {
+        await fs.rename(gitignoreSrc, path.join(targetDir, ".gitignore"));
+    }
+    // Git init
+    if (config.git) {
+        try {
+            execSync("git init", { cwd: targetDir, stdio: "ignore" });
+            console.log(chalk.dim("  Initialized git repository"));
+        }
+        catch {
+            // Git not available, skip
+        }
+    }
+    // npm install
+    if (config.install) {
+        console.log(chalk.dim("  Installing dependencies..."));
+        try {
+            execSync("npm install", { cwd: targetDir, stdio: "ignore" });
+            console.log(chalk.dim("  Dependencies installed"));
+        }
+        catch {
+            console.log(chalk.yellow("  Could not install dependencies. Run 'npm install' manually."));
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runPrompts } from "./prompts.js";
+import { generateProject } from "./generator.js";
+import chalk from "chalk";
+const program = new Command();
+program
+    .name("create-mcp-server")
+    .description("Scaffold a new MCP server project with TypeScript and secure defaults")
+    .version("0.1.0")
+    .argument("[project-name]", "Name of the project to create")
+    .option("-t, --template <template>", "Template to use (minimal, full, http)", "minimal")
+    .option("--no-install", "Skip npm install")
+    .option("--no-git", "Skip git init")
+    .action(async (projectName, options) => {
+    console.log();
+    console.log(chalk.bold.cyan("  ⚡ create-mcp-server"));
+    console.log(chalk.dim("  Scaffold a new MCP server in seconds"));
+    console.log();
+    try {
+        const config = await runPrompts(projectName, options);
+        await generateProject(config);
+        console.log();
+        console.log(chalk.green("  ✓ Project created successfully!"));
+        console.log();
+        console.log(`  ${chalk.dim("$")} cd ${config.projectName}`);
+        if (options.install !== false) {
+            console.log(`  ${chalk.dim("$")} npm run build`);
+        }
+        else {
+            console.log(`  ${chalk.dim("$")} npm install`);
+            console.log(`  ${chalk.dim("$")} npm run build`);
+        }
+        console.log(`  ${chalk.dim("$")} node dist/index.js`);
+        console.log();
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "cancelled") {
+            console.log(chalk.yellow("\n  Cancelled."));
+            process.exit(0);
+        }
+        console.error(chalk.red(`\n  Error: ${error}`));
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/prompts.d.ts

@@ -0,0 +1,12 @@
+export interface ProjectConfig {
+    projectName: string;
+    description: string;
+    template: "minimal" | "full" | "http";
+    install: boolean;
+    git: boolean;
+}
+export declare function runPrompts(projectName: string | undefined, options: {
+    template?: string;
+    install?: boolean;
+    git?: boolean;
+}): Promise<ProjectConfig>;

package/dist/prompts.js

@@ -0,0 +1,53 @@
+import prompts from "prompts";
+import chalk from "chalk";
+const TEMPLATES = [
+    {
+        title: `${chalk.bold("minimal")} ${chalk.dim("— Single tool, stdio transport")}`,
+        value: "minimal",
+    },
+    {
+        title: `${chalk.bold("full")} ${chalk.dim("— Tools + Resources + Prompts, Vitest included")}`,
+        value: "full",
+    },
+    {
+        title: `${chalk.bold("http")} ${chalk.dim("— Streamable HTTP transport with Express")}`,
+        value: "http",
+    },
+];
+export async function runPrompts(projectName, options) {
+    const questions = [];
+    if (!projectName) {
+        questions.push({
+            type: "text",
+            name: "projectName",
+            message: "Project name:",
+            initial: "my-mcp-server",
+            validate: (value) => /^[a-z0-9-_]+$/.test(value) || "Only lowercase letters, numbers, hyphens, and underscores",
+        });
+    }
+    if (!options.template) {
+        questions.push({
+            type: "select",
+            name: "template",
+            message: "Template:",
+            choices: [...TEMPLATES],
+        });
+    }
+    questions.push({
+        type: "text",
+        name: "description",
+        message: "Description:",
+        initial: "A Model Context Protocol server",
+    });
+    const onCancel = () => {
+        throw new Error("cancelled");
+    };
+    const answers = await prompts(questions, { onCancel });
+    return {
+        projectName: projectName || answers.projectName,
+        description: answers.description || "A Model Context Protocol server",
+        template: options.template || answers.template || "minimal",
+        install: options.install !== false,
+        git: options.git !== false,
+    };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nexus-lab/create-mcp-server",
+  "version": "0.1.0",
+  "description": "Scaffold a new MCP server project with TypeScript, testing, and secure defaults",
+  "type": "module",
+  "bin": {
+    "create-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "scaffold",
+    "template",
+    "cli",
+    "create"
+  ],
+  "author": "Nexus Lab",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^13.0.0",
+    "prompts": "^2.4.2",
+    "chalk": "^5.4.0",
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "@types/prompts": "^2.4.9",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/full/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+*.log
+.env
+coverage

package/templates/full/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "my-mcp-server",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A full-featured MCP server with tools, resources, and prompts",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/templates/full/src/index.ts

@@ -0,0 +1,28 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+import { registerResources } from "./resources.js";
+import { registerPrompts } from "./prompts.js";
+
+// Create the MCP server instance
+const server = new McpServer({
+  name: "my-mcp-server",
+  version: "0.1.0",
+});
+
+// Register all capabilities
+registerTools(server);
+registerResources(server);
+registerPrompts(server);
+
+// Connect via stdio transport
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("MCP server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/templates/full/src/prompts.ts

@@ -0,0 +1,32 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// Register prompts on the MCP server
+export function registerPrompts(server: McpServer): void {
+  server.prompt(
+    "review-code",
+    "Review the provided code and suggest improvements",
+    { code: z.string().describe("The source code to review") },
+    ({ code }) => ({
+      messages: [
+        {
+          role: "user" as const,
+          content: {
+            type: "text" as const,
+            text: [
+              "Please review the following code and provide feedback on:",
+              "1. Code quality and readability",
+              "2. Potential bugs or edge cases",
+              "3. Performance considerations",
+              "4. Suggested improvements",
+              "",
+              "```",
+              code,
+              "```",
+            ].join("\n"),
+          },
+        },
+      ],
+    })
+  );
+}

package/templates/full/src/resources.ts

@@ -0,0 +1,34 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// Example application config returned as a resource
+const appConfig = {
+  appName: "my-mcp-server",
+  version: "0.1.0",
+  features: {
+    tools: true,
+    resources: true,
+    prompts: true,
+  },
+  settings: {
+    maxRetries: 3,
+    timeoutMs: 5000,
+  },
+};
+
+// Register resources on the MCP server
+export function registerResources(server: McpServer): void {
+  server.resource(
+    "app-config",
+    "config://app",
+    "Application configuration data",
+    async () => ({
+      contents: [
+        {
+          uri: "config://app",
+          mimeType: "application/json",
+          text: JSON.stringify(appConfig, null, 2),
+        },
+      ],
+    })
+  );
+}

package/templates/full/src/tools.ts

@@ -0,0 +1,59 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// Greeting logic — exported for direct testing
+export function greet(name: string): string {
+  return `Hello, ${name}! Welcome to the MCP server.`;
+}
+
+// Safe expression evaluator — exported for direct testing
+export function calculate(expression: string): string {
+  // Allow only digits, operators, parentheses, dots, and spaces
+  const sanitized = expression.replace(/\s/g, "");
+  if (!/^[\d+\-*/().]+$/.test(sanitized)) {
+    throw new Error(
+      "Invalid expression. Only numbers and +, -, *, /, (, ) are allowed."
+    );
+  }
+
+  // Use Function constructor for safe-ish evaluation of arithmetic
+  const result = new Function(`"use strict"; return (${sanitized});`)();
+
+  if (typeof result !== "number" || !Number.isFinite(result)) {
+    throw new Error("Expression did not evaluate to a finite number.");
+  }
+
+  return String(result);
+}
+
+// Register tools on the MCP server
+export function registerTools(server: McpServer): void {
+  server.tool(
+    "greet",
+    "Generate a greeting for the given name",
+    { name: z.string().describe("The name to greet") },
+    async ({ name }) => ({
+      content: [{ type: "text", text: greet(name) }],
+    })
+  );
+
+  server.tool(
+    "calculate",
+    "Safely evaluate a mathematical expression",
+    {
+      expression: z
+        .string()
+        .describe("Arithmetic expression (e.g. '2 + 3 * 4')"),
+    },
+    async ({ expression }) => {
+      try {
+        const result = calculate(expression);
+        return { content: [{ type: "text", text: result }] };
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Unknown error";
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+      }
+    }
+  );
+}

package/templates/full/tests/tools.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import { greet, calculate } from "../src/tools.js";
+
+describe("greet", () => {
+  it("returns a greeting with the given name", () => {
+    const result = greet("Alice");
+    expect(result).toBe("Hello, Alice! Welcome to the MCP server.");
+  });
+
+  it("handles empty string", () => {
+    const result = greet("");
+    expect(result).toBe("Hello, ! Welcome to the MCP server.");
+  });
+});
+
+describe("calculate", () => {
+  it("evaluates simple addition", () => {
+    expect(calculate("2 + 3")).toBe("5");
+  });
+
+  it("evaluates multiplication with precedence", () => {
+    expect(calculate("2 + 3 * 4")).toBe("14");
+  });
+
+  it("evaluates expressions with parentheses", () => {
+    expect(calculate("(2 + 3) * 4")).toBe("20");
+  });
+
+  it("evaluates decimal numbers", () => {
+    expect(calculate("1.5 + 2.5")).toBe("4");
+  });
+
+  it("rejects expressions with invalid characters", () => {
+    expect(() => calculate("require('fs')")).toThrow("Invalid expression");
+  });
+
+  it("rejects alphabetic input", () => {
+    expect(() => calculate("abc")).toThrow("Invalid expression");
+  });
+
+  it("rejects division by zero (Infinity)", () => {
+    expect(() => calculate("1/0")).toThrow(
+      "Expression did not evaluate to a finite number"
+    );
+  });
+});

package/templates/full/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/templates/full/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+  },
+});

package/templates/http/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+.env

package/templates/http/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "my-mcp-server",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "cors": "^2.8.5",
+    "express": "^4.21.2",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.2",
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  }
+}

package/templates/http/src/index.ts

@@ -0,0 +1,106 @@
+import express from "express";
+import cors from "cors";
+import { randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { z } from "zod";
+
+const app = express();
+
+app.use(cors());
+app.use(express.json());
+
+// Store active transports keyed by session ID
+const transports = new Map<string, StreamableHTTPServerTransport>();
+
+/** Create a new MCP server instance and register tools */
+function createServer(): McpServer {
+  const server = new McpServer({
+    name: "my-mcp-server",
+    version: "0.1.0",
+  });
+
+  // Example tool: hello
+  server.tool(
+    "hello",
+    "Returns a greeting for the given name",
+    { name: z.string().describe("Name to greet") },
+    async ({ name }) => ({
+      content: [{ type: "text", text: `Hello, ${name}!` }],
+    }),
+  );
+
+  return server;
+}
+
+// POST /mcp — handle JSON-RPC requests (initialize + all subsequent calls)
+app.post("/mcp", async (req, res) => {
+  try {
+    // Check for existing session
+    const sessionId = req.headers["mcp-session-id"] as string | undefined;
+
+    if (sessionId && transports.has(sessionId)) {
+      // Route to existing transport
+      const transport = transports.get(sessionId)!;
+      await transport.handleRequest(req, res);
+      return;
+    }
+
+    // No valid session — create a new one (expects an initialize request)
+    const newSessionId = randomUUID();
+    const transport = new StreamableHTTPServerTransport({
+      sessionId: newSessionId,
+    });
+
+    transports.set(newSessionId, transport);
+
+    // Clean up on close
+    transport.onclose = () => {
+      transports.delete(newSessionId);
+    };
+
+    // Connect a fresh server to this transport
+    const server = createServer();
+    await server.connect(transport);
+
+    // Handle the incoming request
+    await transport.handleRequest(req, res);
+  } catch (err) {
+    console.error("Error handling POST /mcp:", err);
+    if (!res.headersSent) {
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+});
+
+// GET /mcp — SSE stream for server-to-client notifications
+app.get("/mcp", async (req, res) => {
+  const sessionId = req.headers["mcp-session-id"] as string | undefined;
+
+  if (!sessionId || !transports.has(sessionId)) {
+    res.status(400).json({ error: "Invalid or missing session ID" });
+    return;
+  }
+
+  const transport = transports.get(sessionId)!;
+  await transport.handleRequest(req, res);
+});
+
+// DELETE /mcp — terminate a session
+app.delete("/mcp", async (req, res) => {
+  const sessionId = req.headers["mcp-session-id"] as string | undefined;
+
+  if (!sessionId || !transports.has(sessionId)) {
+    res.status(400).json({ error: "Invalid or missing session ID" });
+    return;
+  }
+
+  const transport = transports.get(sessionId)!;
+  await transport.handleRequest(req, res);
+});
+
+const PORT = parseInt(process.env.PORT || "3000", 10);
+
+app.listen(PORT, () => {
+  console.log(`MCP server listening on http://localhost:${PORT}/mcp`);
+});

package/templates/http/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src"]
+}

package/templates/minimal/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+.env

package/templates/minimal/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "my-mcp-server",
+  "version": "0.1.0",
+  "description": "A minimal MCP server",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  }
+}

package/templates/minimal/src/index.ts

@@ -0,0 +1,27 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// Create the MCP server
+const server = new McpServer({
+  name: "my-mcp-server",
+  version: "0.1.0",
+});
+
+// Register a simple greeting tool
+server.tool(
+  "hello",
+  "Greet someone by name",
+  { name: z.string().describe("Name of the person to greet") },
+  async ({ name }) => ({
+    content: [{ type: "text", text: `Hello, ${name}!` }],
+  })
+);
+
+// Start the server with stdio transport
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/templates/minimal/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src"]
+}