TypeScript MCP Server Starter

Minimal typed scaffold for a local Model Context Protocol stdio server. It ships two small read-only tools and enough tests, CI, and smoke verification to start replacing example behavior with real domain logic.

Included:

• Strict TypeScript build on Node.js 20 or newer.
• MCP SDK server with structured input and output schemas.
• Two read-only example tools: echo and server_status.
• Node built-in unit tests and an in-memory MCP integration test.
• Local launcher for actual mcp-smoke startup and tool discovery.
• GitHub Actions checks for typecheck, tests, build, and smoke verification.

Run With npx

After npm publication, run the pinned starter server without cloning:

npx -y ryanngit-mcp-server-starter@0.1.0

The process uses stdio and waits silently for MCP JSON-RPC input. Logs belong on stderr so stdout remains protocol-only.

For source development after GitHub publication:

git clone https://github.com/ryanngit/mcp-server-starter.git
cd mcp-server-starter
npm ci
npm run verify
npm run build
node .\dist\src\index.js

Claude Desktop

Add this entry to Claude Desktop configuration. It uses the future pinned npm release and requires no local source path.

{
  "mcpServers": {
    "mcp-server-starter": {
      "command": "npx",
      "args": ["-y", "ryanngit-mcp-server-starter@0.1.0"]
    }
  }
}

Configuration locations:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Save the file and restart Claude Desktop. On Windows, if Claude cannot resolve npx, use "command": "cmd" and prepend "/c", "npx" to args.

Example Tools

Echo validated input:

{
  "name": "echo",
  "arguments": { "message": "hello MCP" },
  "result": { "message": "hello MCP", "characterCount": 9 }
}

Read server identity:

{
  "name": "server_status",
  "arguments": {},
  "result": {
    "status": "ok",
    "server": "mcp-server-starter",
    "version": "0.1.0"
  }
}

Project Layout

src/index.ts                 stdio entrypoint
src/config.ts                shared server name and version
src/server.ts                MCP registration
src/tools.ts                 schemas and typed handlers
scripts/run-mcp-smoke.ts     local smoke launcher
test/                        unit and MCP integration tests
.github/workflows/ci.yml     continuous integration

Development

npm run typecheck
npm test
npm run verify
npm audit --audit-level=high
npm pack --dry-run --json

Package metadata exposes dist/src/server.js and the executable mcp-server-starter bin. Package tests guard repository and license metadata against unresolved publication markers.

Run mcp-smoke

Python 3.11 or newer is needed only for this optional check.

git clone --branch v0.1.0 --depth 1 https://github.com/ryanngit/mcp-smoke.git .mcp-smoke
$env:MCP_SMOKE_PATH = (Resolve-Path .\.mcp-smoke\mcp_smoke.py)
npm run smoke

macOS or Linux:

git clone --branch v0.1.0 --depth 1 https://github.com/ryanngit/mcp-smoke.git .mcp-smoke
MCP_SMOKE_PATH="$PWD/.mcp-smoke/mcp_smoke.py" npm run smoke

The launcher starts the built server, initializes MCP, calls tools/list, and requires at least one tool. It does not invoke tools or certify domain behavior. Server and report identity derive from SERVER_NAME and SERVER_VERSION in src/config.ts.

Optional variables:

Variable	Purpose
MCP_SMOKE_PATH	Required path to mcp_smoke.py.
MCP_SMOKE_OUT	Report directory; defaults to mcp-smoke-out.
PYTHON	Python executable; defaults to python on Windows and python3 elsewhere.

Customize

1. Change package name, description, repository URLs, and bin name in package.json.
2. Change server name and version once in src/config.ts; MCP metadata, status output, error prefix, and smoke identity derive from that config.
3. Replace example schemas and handlers in src/tools.ts.
4. Register tools in src/server.ts; keep stdout protocol-only.
5. Set license year and holder for the resulting project.
6. Run npm run verify, npm run smoke, and npm pack --dry-run --json.

Input schemas are trust boundaries. Keep limits and validation for external values. Return isError: true for expected tool failures instead of printing errors to stdout.

Limitations

• This starter provides no authentication, persistence, prompts, resources, HTTP transport, deployment configuration, or production observability.
• Example tools are intentionally local and stateless.
• mcp-smoke verifies startup and tool discovery only.
• Renaming requires synchronized package metadata and src/config.ts changes.

Support

Search or open a reproducible report in GitHub Issues. Include starter version, Node.js version, platform, sanitized config, and error text. Do not include credentials or private conversation content.

License

MIT. Copyright (c) 2026 ryanngit.