# 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:

```powershell
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:

```powershell
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.

```json
{
  "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:

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

Read server identity:

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

## Project Layout

```text
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

```powershell
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.

```powershell
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:

```bash
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](https://github.com/ryanngit/mcp-server-starter/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.