wm-create-mcp-server 0.1.0

package/src/templates/full/README.md

@@ -0,0 +1,76 @@
+# {{PROJECT_NAME}}
+
+An MCP server built with [create-mcp-server](https://github.com/workingmodel/wm-create-mcp-server).
+
+## Commands
+
+```bash
+npm run dev          # start server in watch mode
+npm run inspector    # build + open MCP Inspector UI
+npm run test         # run unit tests
+npm run validate     # typecheck + tests
+npm run build        # compile to dist/
+npm run docker:build # build Docker image
+npm run docker:run   # start via docker compose
+```
+
+## Project structure
+
+```
+src/
+  tools/
+    index.ts         ← register all tools here
+    echo.ts          ← example: echo tool
+    get-weather.ts   ← example: weather tool (stub)
+    __tests__/       ← vitest unit tests per tool
+  resources/
+    index.ts         ← MCP resource definitions
+  prompts/
+    index.ts         ← MCP prompt templates
+  auth/
+    index.ts         ← API key auth stub
+  lib/
+    tool-builder.ts  ← defineTool() + registerTools()
+  server.ts          ← MCP server setup
+  index.ts           ← transport entry point
+```
+
+## Adding a tool
+
+1. Create `src/tools/my-tool.ts`:
+
+```ts
+import { z } from "zod";
+import { defineTool, text } from "../lib/tool-builder.js";
+
+export const myTool = defineTool({
+  name: "my-tool",
+  description: "What this tool does",
+  input: z.object({
+    param: z.string().describe("Description of param"),
+  }),
+  handler: async ({ param }) => text(`Result: ${param}`),
+});
+```
+
+2. Add to `src/tools/index.ts`:
+
+```ts
+import { myTool } from "./my-tool.js";
+export const tools = [...existingTools, myTool];
+```
+
+## Connecting to Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "{{PROJECT_NAME}}": {
+      "command": "node",
+      "args": ["/absolute/path/to/{{PROJECT_NAME}}/dist/index.js"]
+    }
+  }
+}
+```

package/src/templates/full/_dot_env.example

@@ -0,0 +1,3 @@
+# Copy this file to .env and fill in values
+# Add your API keys and config here
+# SOME_API_KEY=your_key_here

package/src/templates/full/_dot_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.env
+.DS_Store

package/src/templates/full/_dot_vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "vitest.explorer"
+  ]
+}

package/src/templates/full/docker-compose.yml

@@ -0,0 +1,8 @@
+services:
+  mcp-server:
+    build: .
+    ports:
+      - "3000:3000"
+    env_file:
+      - .env
+    restart: unless-stopped

package/src/templates/full/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "{{VERSION}}",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx --watch src/index.ts",
+    "dev:sse": "tsx --watch src/index.sse.ts",
+    "build": "tsup src/index.ts src/index.sse.ts --format esm --out-dir dist",
+    "start": "node dist/index.js",
+    "start:sse": "node dist/index.sse.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "inspector": "npm run build && npx @modelcontextprotocol/inspector node dist/index.js",
+    "validate": "npm run typecheck && npm run test",
+    "docker:build": "docker build -t {{PROJECT_NAME}} .",
+    "docker:run": "docker compose up"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0",
+    "zod-to-json-schema": "^3.23.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/inspector": "^0.6.0",
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/templates/full/src/auth/index.ts

@@ -0,0 +1,24 @@
+// Auth stub — wire this to your actual auth layer.
+// Currently validates a static API key from the environment.
+// Replace with OAuth2, JWT, or your preferred auth mechanism.
+
+const VALID_API_KEY = process.env.API_KEY;
+
+export interface AuthResult {
+  ok: boolean;
+  reason?: string;
+}
+
+export function validateApiKey(providedKey: string | undefined): AuthResult {
+  if (!VALID_API_KEY) {
+    // No key configured → auth disabled (open access)
+    return { ok: true };
+  }
+  if (!providedKey) {
+    return { ok: false, reason: "Missing API key" };
+  }
+  if (providedKey !== VALID_API_KEY) {
+    return { ok: false, reason: "Invalid API key" };
+  }
+  return { ok: true };
+}

package/src/templates/full/src/index.sse.ts

@@ -0,0 +1,58 @@
+/**
+ * SSE transport entry point — for remote HTTP clients (Cursor, Windsurf, web apps).
+ *
+ * Usage:
+ *   npm run dev:sse      # dev mode
+ *   npm run start:sse    # production
+ *
+ * Connect your MCP client to: http://localhost:PORT/sse
+ */
+import { createServer as createHttpServer, IncomingMessage, ServerResponse } from "node:http";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { createServer } from "./server.js";
+
+const PORT = Number(process.env.PORT ?? 3000);
+
+const mcpServer = createServer();
+
+// Map sessionId → transport so POST /messages can route to the right connection
+const transports = new Map<string, SSEServerTransport>();
+
+const httpServer = createHttpServer(async (req: IncomingMessage, res: ServerResponse) => {
+  const url = new URL(req.url ?? "/", `http://localhost:${PORT}`);
+
+  // Client opens SSE stream
+  if (req.method === "GET" && url.pathname === "/sse") {
+    const transport = new SSEServerTransport("/messages", res);
+    transports.set(transport.sessionId, transport);
+
+    res.on("close", () => {
+      transports.delete(transport.sessionId);
+    });
+
+    await mcpServer.connect(transport);
+    return;
+  }
+
+  // Client posts a message to an established session
+  if (req.method === "POST" && url.pathname === "/messages") {
+    const sessionId = url.searchParams.get("sessionId") ?? "";
+    const transport = transports.get(sessionId);
+
+    if (!transport) {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("Session not found");
+      return;
+    }
+
+    await transport.handlePostMessage(req, res);
+    return;
+  }
+
+  res.writeHead(404, { "Content-Type": "text/plain" });
+  res.end("Not found");
+});
+
+httpServer.listen(PORT, () => {
+  console.log(`{{PROJECT_NAME}} MCP server (SSE) listening on http://localhost:${PORT}/sse`);
+});

package/src/templates/full/src/index.ts

@@ -0,0 +1,6 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/templates/full/src/lib/tool-builder.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export interface ToolResult {
+  content: Array<
+    | { type: "text"; text: string }
+    | { type: "image"; data: string; mimeType: string }
+  >;
+  isError?: boolean;
+  [key: string]: unknown;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ToolDefinition<TInput extends z.ZodRawShape = any> {
+  name: string;
+  description: string;
+  input: z.ZodObject<TInput>;
+  handler: (input: z.infer<z.ZodObject<TInput>>) => Promise<ToolResult>;
+}
+
+export function defineTool<TInput extends z.ZodRawShape>(
+  definition: ToolDefinition<TInput>
+): ToolDefinition<TInput> {
+  return definition;
+}
+
+export function registerTools(server: McpServer, tools: ToolDefinition[]) {
+  for (const tool of tools) {
+    server.tool(
+      tool.name,
+      tool.description,
+      tool.input.shape,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      async (input: any) => tool.handler(input)
+    );
+  }
+}
+
+export function text(content: string): ToolResult {
+  return { content: [{ type: "text", text: content }] };
+}
+
+export function error(message: string): ToolResult {
+  return { content: [{ type: "text", text: message }], isError: true };
+}

package/src/templates/full/src/prompts/index.ts

@@ -0,0 +1,41 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+export function registerPrompts(server: McpServer) {
+  server.prompt(
+    "summarize",
+    "Summarize a piece of text concisely",
+    { text: z.string().describe("The text to summarize") },
+    ({ text }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Please summarize the following text in 2-3 sentences:\n\n${text}`,
+          },
+        },
+      ],
+    })
+  );
+
+  server.prompt(
+    "improve-writing",
+    "Improve the clarity and style of a piece of writing",
+    {
+      text: z.string().describe("The text to improve"),
+      tone: z.enum(["professional", "casual", "concise"]).default("professional"),
+    },
+    ({ text, tone }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Rewrite the following text with a ${tone} tone, improving clarity and style:\n\n${text}`,
+          },
+        },
+      ],
+    })
+  );
+}

package/src/templates/full/src/resources/index.ts

@@ -0,0 +1,37 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export function registerResources(server: McpServer) {
+  // Static resource example
+  server.resource(
+    "config",
+    "mcp://{{PROJECT_NAME}}/config",
+    async (uri) => ({
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify({ name: "{{PROJECT_NAME}}", version: "{{VERSION}}" }, null, 2),
+        },
+      ],
+    })
+  );
+
+  // Dynamic resource example (parameterized URI template)
+  server.resource(
+    "item",
+    new ResourceTemplate("mcp://{{PROJECT_NAME}}/items/{id}", { list: undefined }),
+    async (uri) => {
+      const id = uri.pathname.split("/").pop();
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/plain",
+            text: `Item ${id} content here. Replace with real data lookup.`,
+          },
+        ],
+      };
+    }
+  );
+}

package/src/templates/full/src/server.ts

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./lib/tool-builder.js";
+import { tools } from "./tools/index.js";
+import { registerResources } from "./resources/index.js";
+import { registerPrompts } from "./prompts/index.js";
+
+export function createServer(): McpServer {
+  const server = new McpServer({
+    name: "{{PROJECT_NAME}}",
+    version: "{{VERSION}}",
+  });
+
+  registerTools(server, tools);
+  registerResources(server);
+  registerPrompts(server);
+
+  return server;
+}

package/src/templates/full/src/tools/__tests__/echo.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from "vitest";
+import { echoTool } from "../echo.js";
+
+describe("echo tool", () => {
+  it("returns the input message", async () => {
+    const result = await echoTool.handler({ message: "hello world" });
+    expect(result.content[0]).toEqual({ type: "text", text: "hello world" });
+  });
+
+  it("handles empty string", async () => {
+    const result = await echoTool.handler({ message: "" });
+    expect(result.content[0]).toEqual({ type: "text", text: "" });
+  });
+});

package/src/templates/full/src/tools/__tests__/get-weather.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from "vitest";
+import { getWeatherTool } from "../get-weather.js";
+
+describe("get-weather tool", () => {
+  it("returns weather for a location in celsius", async () => {
+    const result = await getWeatherTool.handler({ location: "London", units: "celsius" });
+    expect(result.content[0].type).toBe("text");
+    expect((result.content[0] as { type: "text"; text: string }).text).toContain("London");
+    expect((result.content[0] as { type: "text"; text: string }).text).toContain("°C");
+  });
+
+  it("returns weather in fahrenheit", async () => {
+    const result = await getWeatherTool.handler({ location: "New York", units: "fahrenheit" });
+    expect((result.content[0] as { type: "text"; text: string }).text).toContain("°F");
+  });
+});

package/src/templates/full/src/tools/echo.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { defineTool, text } from "../lib/tool-builder.js";
+
+export const echoTool = defineTool({
+  name: "echo",
+  description: "Returns the input message unchanged. Useful for testing your server connection.",
+  input: z.object({
+    message: z.string().describe("The message to echo back"),
+  }),
+  handler: async ({ message }) => text(message),
+});

package/src/templates/full/src/tools/get-weather.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { defineTool, text, error } from "../lib/tool-builder.js";
+
+// Example tool showing a realistic pattern: validated input, error handling, typed output.
+// Replace with your own logic or delete this file.
+export const getWeatherTool = defineTool({
+  name: "get-weather",
+  description: "Get the current weather for a city. Returns temperature and conditions.",
+  input: z.object({
+    location: z.string().describe("City name, e.g. 'New York' or 'London, UK'"),
+    units: z
+      .enum(["celsius", "fahrenheit"])
+      .default("celsius")
+      .describe("Temperature unit"),
+  }),
+  handler: async ({ location, units }) => {
+    // TODO: Replace with a real weather API call
+    // e.g. const data = await fetch(`https://api.openweathermap.org/...`)
+
+    // Stub response for demonstration
+    const temp = units === "celsius" ? "22°C" : "72°F";
+    return text(`Weather in ${location}: ${temp}, partly cloudy.`);
+  },
+});

package/src/templates/full/src/tools/index.ts

@@ -0,0 +1,9 @@
+import type { ToolDefinition } from "../lib/tool-builder.js";
+import { echoTool } from "./echo.js";
+import { getWeatherTool } from "./get-weather.js";
+
+// Register all tools here. Import and add to this array.
+export const tools: ToolDefinition[] = [
+  echoTool,
+  getWeatherTool,
+];

package/src/templates/full/tsconfig.json

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

package/src/templates/full/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/__tests__/**/*.test.ts"],
+  },
+});

package/src/templates/minimal/README.md

@@ -0,0 +1,41 @@
+# {{PROJECT_NAME}}
+
+An MCP server built with [create-mcp-server](https://github.com/workingmodel/create-mcp-server).
+
+## Getting started
+
+```bash
+npm run dev        # start server in watch mode (stdio transport)
+npm run build      # compile to dist/
+npm run start      # run compiled server
+```
+
+## Adding tools
+
+Edit `src/index.ts` and add a new `server.tool()` call:
+
+```ts
+server.tool(
+  "my-tool",
+  "What this tool does",
+  { param: z.string() },
+  async ({ param }) => ({
+    content: [{ type: "text", text: `Result: ${param}` }],
+  })
+);
+```
+
+## Connecting to Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "{{PROJECT_NAME}}": {
+      "command": "node",
+      "args": ["/absolute/path/to/{{PROJECT_NAME}}/dist/index.js"]
+    }
+  }
+}
+```

package/src/templates/minimal/_dot_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.env
+.DS_Store

package/src/templates/minimal/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "{{VERSION}}",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx --watch src/index.ts",
+    "build": "tsup src/index.ts --format esm --out-dir dist",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/templates/minimal/src/index.ts

@@ -0,0 +1,21 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const server = new McpServer({
+  name: "{{PROJECT_NAME}}",
+  version: "{{VERSION}}",
+});
+
+// Example tool — replace or extend this
+server.tool(
+  "echo",
+  "Returns the input message unchanged",
+  { message: z.string().describe("The message to echo back") },
+  async ({ message }) => ({
+    content: [{ type: "text", text: message }],
+  })
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/templates/minimal/tsconfig.json

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

package/src/templates/standard/.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm install
+      - run: npm run typecheck
+      - run: npm test