gh repo create my-mcp-server --template starter-series/mcp-server-starter --clone
cd my-mcp-server && npm install && npm run dev

git clone https://github.com/starter-series/mcp-server-starter my-mcp-server
cd my-mcp-server && npm install && npm run dev

import { z } from 'zod';
import { ok, err } from '../helpers.js';

export const name = 'your_tool';

export const config = {
  title: 'Your Tool',
  description: 'What your tool does',
  inputSchema: {
    input: z.string().describe('Input parameter'),
  },
  // Declare `outputSchema` to return structured results — the 2026 MCP spec
  // requires servers to populate `structuredContent` (validated against this
  // schema) alongside the text mirror. Omit `outputSchema` for free-form
  // text-only tools.
  outputSchema: {
    result: z.string().describe('Processed value'),
  },
  annotations: {
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
    openWorldHint: false,
  },
};

export async function handler({ input }: { input: string }) {
  try {
    const result = `Processed: ${input}`;
    // Pass the structured payload as the second arg to `ok()` — it's set as
    // `structuredContent` alongside the text mirror in `content[]`.
    return ok(result, { result });
  } catch (e) {
    return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
  }
}

import * as yourTool from './tools/your-tool.js';
server.registerTool(yourTool.name, yourTool.config, yourTool.handler);

import { z } from 'zod';

export const name = 'your-prompt';
export const title = 'Your Prompt';
export const description = 'Guided workflow description';

export const argsSchema = {
  param: z.string().min(1).describe('Required parameter'),
};

export function handler({ param }: { param: string }) {
  return {
    description,
    messages: [{
      role: 'user' as const,
      content: { type: 'text' as const, text: `Prompt text with ${param}` },
    }],
  };
}

import * as yourPrompt from './prompts/your-prompt.js';
server.registerPrompt(
  yourPrompt.name,
  { title: yourPrompt.title, description: yourPrompt.description, argsSchema: yourPrompt.argsSchema },
  yourPrompt.handler,
);

export const name = 'your-resource';
export const uri = 'info://your/resource';

export const metadata = {
  title: 'Your Resource',
  description: 'What this resource exposes',
  mimeType: 'application/json',
};

export async function handler(resourceUri: URL) {
  return {
    contents: [{ uri: resourceUri.href, mimeType: metadata.mimeType, text: '...' }],
  };
}

import * as yourResource from './resources/your-resource.js';
server.registerResource(yourResource.name, yourResource.uri, yourResource.metadata, yourResource.handler);

import express from 'express';
import { randomUUID } from 'node:crypto';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
import { createServer } from 'my-mcp-server';

const app = express();
app.use(express.json());

const sessions = new Map<string, StreamableHTTPServerTransport>();

app.post('/mcp', async (req, res) => {
  const sessionId = req.headers['mcp-session-id'] as string;
  const existing = sessions.get(sessionId);

  if (existing) {
    await existing.handleRequest(req, res);
    return;
  }

  if (!isInitializeRequest(req.body)) {
    res.status(400).json({ error: 'Bad Request: Not an initialize request' });
    return;
  }

  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: () => randomUUID(),
  });

  transport.onclose = () => {
    const id = transport.sessionId;
    if (id) sessions.delete(id);
  };

  const server = createServer();
  await server.connect(transport);
  if (transport.sessionId) sessions.set(transport.sessionId, transport);
  await transport.handleRequest(req, res);
});

app.get('/mcp', async (req, res) => {
  const t = sessions.get(req.headers['mcp-session-id'] as string);
  if (!t) return res.status(400).end();
  await t.handleRequest(req, res);
});

app.delete('/mcp', async (req, res) => {
  const t = sessions.get(req.headers['mcp-session-id'] as string);
  if (!t) return res.status(400).end();
  await t.handleRequest(req, res);
});

app.listen(3000);

npm run build
npm run smoke:mcp
npm run pack:check
npx @modelcontextprotocol/inspector node dist/index.js

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

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    }
  }
}

src/
├── index.ts              # Server entry — tool/resource/prompt registration + transport
├── config.ts             # Environment variable config
├── helpers.ts            # ok() / err() response helpers
├── tools/
│   └── greet.ts          # Example tool with annotations (replace with your own)
├── resources/
│   └── server-info.ts    # Example resource exposing server metadata (replace)
└── prompts/
    ├── hello.ts          # Zero-arg prompt example (replace with your own)
    └── code-review.ts    # Templated prompt with Zod-validated args
tests/
├── greet.test.js         # Tool tests
├── helpers.test.js       # Helper tests
├── server-info.test.js   # Resource tests
├── hello.test.js         # Prompt tests
└── code-review.test.js   # Templated prompt tests