impossible-mcp

Impossible MCP Template

A TypeScript foundation for building Model Context Protocol servers that run locally over stdio or remotely over Streamable HTTP. Fork it, replace the example capabilities, and keep the operational pieces.

Included

• MCP tools, resources, prompts, and parameterized resources
• stdio and Streamable HTTP transports from one server factory
• health and readiness routes for HTTP deployments
• validated environment configuration and structured logs
• graceful process shutdown
• strict TypeScript, tests, coverage gates, linting, formatting, and CI
• Docker and Compose definitions
• security, contribution, and release documentation

Start locally

npm install
cp .env.example .env
npm run dev

The default transport is stdio. Run the HTTP service with:

MCP_TRANSPORT=http npm run dev

On PowerShell:

$env:MCP_TRANSPORT = "http"
npm run dev

The MCP endpoint is http://127.0.0.1:3333/mcp. Health checks are available at /healthz and /readyz.

Connect over stdio

Build the project and point an MCP host at the executable:

{
  "mcpServers": {
    "impossible-template": {
      "command": "node",
      "args": ["/absolute/path/to/impossible-mcp-template/dist/cli.js"]
    }
  }
}

Make it yours

Start in src/server.ts. Replace the example echo and server-time tools, then update the resources and prompts. Keep application secrets in environment variables and add them to the logger's redaction paths.

The project separates transport wiring from capability registration. Tests can instantiate the server factory without opening a production port, and both transports expose the same behavior.

Commands

Command	Purpose
npm run dev	Run the server with file watching
npm run build	Compile the production package
npm test	Run the test suite once
npm run test:coverage	Enforce coverage thresholds
npm run lint	Check TypeScript and JavaScript rules
npm run format	Check repository formatting
npm run verify	Run the complete local verification pipeline

Documentation

• Architecture
• Capabilities
• Configuration
• Deployment
• Operations
• Observability
• Security model
• Testing
• Troubleshooting

License

MIT