Skip to main content
Glama
colossal1598

ship-mcp

by colossal1598

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.

Related MCP server: MCP Server Boilerplate

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.

Available Tools

2 tools
echoEchoA

Echo a message back — the hello-world of MCP tools.

ParametersJSON Schema
NameRequiredDescriptionDefault
messageYesText to echo back

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Since no annotations are provided, the description carries the burden of behavioral disclosure. 'Echo a message back' conveys a side-effect-free operation and implies that the return value is the same message. The 'hello-world' comment adds useful context about the tool's simplicity, though it does not explicitly state the absence of side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that directly states the core behavior. The 'hello-world of MCP tools' phrase adds a small amount of contextual color without significant bloat, making the description concise and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, trivial tool with no output schema, the description is sufficiently complete. It states what the tool does, the required parameter is fully documented in the schema, and the return behavior is clearly implied by 'echo back.' Nothing important is missing for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers the only parameter, message, with a clear description and 100% coverage. The tool description adds no additional semantic detail about the parameter, such as formatting, examples, or constraints, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: it echoes a message back. This is a specific verb and resource, and the purpose is immediately understandable. It does not explicitly distinguish itself from the sibling fetch_json, but the contrast is evident from the name and description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use echo versus fetch_json or any other alternative. The 'hello-world' phrase hints at testing or demonstration use, but the description never states that this is for verifying connectivity or debugging, nor does it mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fetch_jsonFetch JSONA

Fetch a JSON payload from an HTTPS URL and return it prettified.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesHTTPS URL returning JSON

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose the HTTPS-only constraint and the prettified return format, which are useful. However, it omits potential network side effects, timeouts, error behavior, or size limits that could matter for an arbitrary-URL fetch.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one concise sentence that is front-loaded with the verb and resource, followed by the output format. Every word earns its place and nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description explains the action and the return treatment sufficiently for an agent to invoke it successfully. Additional error-handling or security caveats would improve it, but they are not necessary for basic correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage of the single 'url' parameter, including its format and description. The tool description adds essentially no information beyond what the schema already states, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Fetch' with a clear resource ('JSON payload from an HTTPS URL') and states the output transformation ('return it prettified'). This makes the tool's purpose immediately distinguishable from the sibling 'echo', which would not involve remote retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used when remote JSON is needed, but it provides no explicit guidance about when not to use it or how it compares to the sibling 'echo'. There is no alternative routing, only an implied usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

A3.6/5.0
Disambiguation5/5

echo and fetch_json are completely distinct operations with no functional overlap. An agent can easily tell them apart based on purpose alone.

Naming Consistency4/5

Both tool names are short imperative verbs, but 'echo' is a bare verb while 'fetch_json' follows a verb_noun pattern. The inconsistency is minor and readability remains high.

Tool Count3/5

At 2 tools, the server feels thin and borderline for a general-purpose utility set. However, the tools are simple and self-contained, so the count is not drastically mismatched for a minimal demo server.

Completeness2/5

The name 'ship-mcp' suggests a deployment or shipping workflow, but the tools only cover echoing and fetching JSON. There are no operations related to shipping, deploying, or managing releases, leaving the apparent domain severely undercovered.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • F
    license
    A
    quality
    D
    maintenance
    A starter template for building custom MCP servers that can integrate with Claude Desktop, Cursor, and other AI assistants. Provides example tools, TypeScript support, and automated publishing workflows to help developers quickly create their own MCP servers.
    7
    16
  • A
    license
    Not graded
    quality
    D
    maintenance
    A TypeScript-based template for rapidly developing MCP servers with modular tool architecture, built-in validation using Zod schemas, and comprehensive error handling.
    13
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    A template for building MCP servers with automatic tool discovery using TypeScript and Zod schemas, supporting HTTP and STDIO transports.
    26,333
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/colossal1598/ship-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server