io.github.colossal1598/ship-mcp

ship-mcp

The clean TypeScript starter for building MCP servers. Zod-validated tools, unit tests, MCP Inspector wired up, one-command dev loop. Clone it, rename two strings, ship your server.

npx degit colossal1598/ship-MCP my-server && cd my-server && npm i && npm run dev

Why this exists

Every MCP server starts with the same 90 minutes of setup: SDK wiring, stdio transport, schema validation, figuring out why console.log breaks the protocol (logs go to stderr — already handled here), and getting the Inspector attached. This repo is that 90 minutes, done properly, once.

What's inside

• src/index.ts — server wiring: register tools, connect stdio transport. ~40 lines, no magic.
• src/tools.ts — tool logic decoupled from wiring so it's unit-testable. Two examples: echo (hello-world) and fetch_json (real async tool with error handling).
• src/tools.test.ts — Vitest tests that run without spawning the server.
• npm run inspect — opens the official MCP Inspector against your dev server.

Quickstart

npm install
npm run dev        # run the server (stdio)
npm test           # unit tests
npm run inspect    # poke tools in the MCP Inspector UI
npm run build      # compile to dist/

Use it from Claude Desktop / Claude Code

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

Add your own tool (30 seconds)

// src/tools.ts
export const greetInput = { name: z.string() };
export async function greet({ name }: { name: string }) {
  return { content: [{ type: "text" as const, text: `Hello, ${name}!` }] };
}

// src/index.ts
server.registerTool("greet", { description: "Greet someone", inputSchema: greetInput }, greet);

---

Want to ship a paid MCP server?

Fewer than 5% of the 11,000+ MCP servers out there make money — not because the demand isn't there, but because the billing plumbing is genuinely annoying. Ship MCP Pro is this starter plus everything the free version deliberately leaves out:

• 🔑 License-key gating — Payhip & Gumroad license verification middleware; sell keys, server validates them
• 📊 Usage metering + per-key rate limits — free tier / paid tier out of the box
• 🌐 Streamable HTTP transport — deploy as a remote server (Docker + Railway/Fly guides included)
• ✅ CI pipeline, expanded test suite, production error handling
• 📣 Launch kit — the exact directory-submission checklist + listing templates that get servers 10x more installs

One-time $49, MIT-licensed output, free updates. → Get Ship MCP Pro

---

MIT © Argo Navis

Note on the SDK pin: this starter pins @modelcontextprotocol/server@2.0.0-beta.5 exactly — the v2 SDK for the 2026-07-28 spec. When the stable 2.0.0 lands, bump the pin and re-run the tests; the exact pin is there so an upstream beta change can't silently break your build.