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

Related MCP server: mcp-anvil-lite

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:

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.