io.github.colossal1598/ship-mcp
Clean TypeScript starter for MCP servers: zod-validated tools, tests, one-command dev loop.
Open source Open in the app JSON README (API)
About
Clean TypeScript starter for MCP servers: zod-validated tools, tests, one-command dev loop.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- colossal1598
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.1
- Last push
- 2026-07-28T16:50:40Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:37
- Updated
- 2026-08-29 03:02:37
- Origin id
io.github.colossal1598/ship-mcp
README
# 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.
```bash
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
```bash
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
```json
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["/absolute/path/to/dist/index.js"]
}
}
}
```
## Add your own tool (30 seconds)
```ts
// 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](https://payhip.com/b/FWSlg)** 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](https://payhip.com/b/FWSlg)**
---
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.