wm-create-mcp-server 0.1.0

package/src/templates/standard/README.md

@@ -0,0 +1,83 @@
+# {{PROJECT_NAME}}
+
+An MCP server built with [create-mcp-server](https://github.com/workingmodel/create-mcp-server).
+
+## Commands
+
+```bash
+npm run dev          # start server in watch mode
+npm run inspector    # open MCP Inspector UI to test tools interactively
+npm run test         # run unit tests
+npm run validate     # typecheck + tests
+npm run build        # compile to dist/
+```
+
+## Project structure
+
+```
+src/
+  tools/
+    index.ts         ← register all tools here
+    echo.ts          ← example: echo tool
+    get-weather.ts   ← example: weather tool (stub — wire to a real API)
+    __tests__/       ← vitest unit tests per tool
+  lib/
+    tool-builder.ts  ← defineTool() helper + 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];
+```
+
+3. Write a test in `src/tools/__tests__/my-tool.test.ts`.
+
+## 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"]
+    }
+  }
+}
+```
+
+## Connecting to Cursor / Windsurf
+
+In your editor's MCP config:
+
+```json
+{
+  "{{PROJECT_NAME}}": {
+    "command": "node",
+    "args": ["/absolute/path/to/{{PROJECT_NAME}}/dist/index.js"]
+  }
+}
+```

package/src/templates/standard/_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/standard/_dot_gitignore

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

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

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

package/src/templates/standard/package.json

@@ -0,0 +1,32 @@
+{
+  "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"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^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/standard/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/standard/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/standard/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/standard/src/server.ts

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

package/src/templates/standard/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/standard/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/standard/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/standard/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/standard/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/standard/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/standard/vitest.config.ts

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