create-mcp-server

name	create-mcp-server
description	Use when a user asks to create, scaffold, bootstrap, or wire up a new MCP server in a repository. Best for local stdio servers that should usually live under .github/mcp/<mcpname>, run via npx from the project, and be added to .vscode/mcp.json.
argument-hint	mcp server name, optional path, tools, env vars, and any custom behavior

Create MCP Server

Use this skill when the user wants a new MCP server scaffolded in a repository.

Default behavior:

• Create the server in .github/mcp/<mcpname> unless the user explicitly asks for another location.
• Implement the server in TypeScript.
• Make it runnable from the project via npx.
• Always create the server itself and update .vscode/mcp.json.
• If the user does not specify a real tool yet, scaffold a single ping tool so the server is valid and testable.

What To Produce

Create or update these artifacts:

• .github/mcp/<mcpname>/package.json
• .github/mcp/<mcpname>/tsconfig.json
• .github/mcp/<mcpname>/src/index.ts
• .vscode/mcp.json

Optional when needed:

• .github/mcp/<mcpname>/.env.example
• .github/mcp/<mcpname>/README.md

Decision Rules

1. If the user did not provide a location, use .github/mcp/<mcpname>.
2. If the user did not define tools, create a minimal ping tool stub.
3. If the server needs secrets or runtime configuration, add placeholders in .env.example and wire them through .vscode/mcp.json via env or inputs; never hardcode secrets.
4. If .vscode/mcp.json does not exist, create it with a top-level servers object.
5. If .vscode/mcp.json already exists, merge the new server entry without deleting or renaming existing servers.
6. For stdio servers, never log to stdout. Use console.error for diagnostics so JSON-RPC traffic is not corrupted.

Recommended Structure

.github/
  mcp/
    <mcpname>/
      package.json
      tsconfig.json
      src/
        index.ts
      .env.example        # optional

Required Commands

Run these commands from the repository root after creating the files:

cd .github/mcp/<mcpname>
npm install
npm run build

Use this servers schema shape in .vscode/mcp.json so VS Code can launch the server from the workspace:

{
  "servers": {
    "<mcpname>": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tsx", "src/index.ts"],
      "cwd": "${workspaceFolder}/.github/mcp/<mcpname>"
    }
  },
  "inputs": []
}

If the server needs environment variables, extend the entry like this:

{
  "servers": {
    "<mcpname>": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tsx", "src/index.ts"],
      "cwd": "${workspaceFolder}/.github/mcp/<mcpname>",
      "env": {
        "EXAMPLE_API_KEY": "${input:example-api-key}",
        "EXAMPLE_API_URL": "https://api.example.com"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "example-api-key",
      "description": "API key for <mcpname>",
      "password": true
    }
  ]
}

File Templates

Create package.json with this baseline content:

{
  "name": "<mcpname>",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "dist/index.js",
  "bin": {
    "<mcpname>": "dist/index.js"
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "tsc",
    "dev": "tsx watch src/index.ts",
    "start": "node dist/index.js"
  },
  "engines": {
    "node": ">=20"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.10.2",
    "zod": "^3.24.2"
  },
  "devDependencies": {
    "@types/node": "^22.14.0",
    "tsx": "^4.19.3",
    "typescript": "^5.8.3"
  }
}

Create tsconfig.json with this baseline content:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "types": ["node"]
  },
  "include": ["src/**/*.ts"]
}

Create src/index.ts with this baseline content:

#!/usr/bin/env node
import { createRequire } from "node:module";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const require = createRequire(import.meta.url);
const { version } = require("../package.json") as { version: string };

const server = new McpServer({
  name: "<mcpname>",
  version,
});

server.tool(
  "ping",
  "Return a simple pong response.",
  {
    message: z.string().optional().describe("Optional message to echo back"),
  },
  async ({ message }) => {
    const text = message ? `pong: ${message}` : "pong";
    return {
      content: [{ type: "text", text }],
    };
  },
);

console.error("[<mcpname>] starting MCP server");

const transport = new StdioServerTransport();
await server.connect(transport);

If the user asked for a real tool instead of the default stub, replace ping with the requested tool implementation while keeping the same server/bootstrap pattern.

Implementation Procedure

1. Normalize the server name. Use a filesystem-safe and npm-safe name such as github-issues-mcp or jira-search-mcp.

2. Choose the path. Default to .github/mcp/<mcpname> unless the user explicitly requests another location.

3. Create the folder structure.

Bash:

mkdir -p .github/mcp/<mcpname>/src

PowerShell:

New-Item -ItemType Directory -Path .github/mcp/<mcpname>/src -Force

4. Create package.json, tsconfig.json, and src/index.ts using the templates above.

5. Install dependencies.

   cd .github/mcp/<mcpname>
   npm install
   

6. Update .vscode/mcp.json. Ensure there is a servers object and add one new entry for <mcpname> that uses:

   • type: "stdio"
   • command: "npx"
   • args: ["-y", "tsx", "src/index.ts"]
   • cwd: "${workspaceFolder}/.github/mcp/<mcpname>"

7. If the server needs runtime configuration, add .env.example and map inputs in .vscode/mcp.json.

8. Validate the scaffold.

   cd .github/mcp/<mcpname>
   npm run build
   

9. Confirm the server is discoverable in VS Code. After saving .vscode/mcp.json, VS Code may prompt for trust or restart. If discovery fails, inspect MCP output logs.

Editing Rules

• Preserve unrelated entries in .vscode/mcp.json.
• Do not hardcode secrets in tracked files.
• Keep code and comments in English.
• Prefer minimal scaffolding over framework-heavy abstractions.
• Keep the first version small and working; add resources, prompts, or apps only if the user asks for them.

Completion Checklist

The task is complete only when all of the following are true:

• The server exists in TypeScript under the requested path, or under .github/mcp/<mcpname> by default.
• The server exposes at least one valid tool.
• The server can be launched through npx from the project context.
• .vscode/mcp.json contains the new server entry and keeps existing entries intact.
• npm install and npm run build succeed for the new server.
• Any required environment variables are represented as placeholders, not hardcoded secrets.
• Logging uses stderr, not stdout.

Good Defaults For Follow-Up

If the user does not specify next steps, offer one of these:

• Replace the ping stub with a real tool.
• Add environment variable support.
• Add a README for the new MCP server.
• Add a second tool or a prompt/resource if the server needs more capability.

Example Requests This Skill Should Handle

• Create a new MCP server named github-issues-mcp in this repo.
• Scaffold a TypeScript MCP server for Jira search under the default .github/mcp location.
• Add a minimal MCP server with one tool and wire it into .vscode/mcp.json.
• Build a local MCP stdio server that VS Code can run with npx.