mcp-blanko

A template for building your own MCP (Model Context Protocol) server in TypeScript.

Includes placeholder tools, dual transport support (stdio + SSE), and a simple pattern for adding your own tools.

Quick Start

npm install
npm run build
npm start

Project Structure

src/
├── index.ts          # Entry point — transport selection
├── server.ts         # Server setup & tool registration
└── tools/
    ├── hello-world.ts      # Simple greeting tool
    ├── complex-input.ts    # Rich input schema with error handling
    ├── async-operation.ts  # Simulated long-running task
    ├── external-api.ts     # Placeholder for API integration
    └── file-operation.ts   # Local file read/write

Adding Your Own Tool

1. Create a new file in src/tools/:

import { z } from "zod";
import type { ToolDefinition } from "../server.js";

export const myTool: ToolDefinition = {
  name: "my_tool",
  description: "What this tool does",
  inputSchema: z.object({
    param: z.string().describe("Description of param"),
  }),
  handler: async ({ param }) => {
    return {
      content: [{ type: "text", text: `Result: ${param}` }],
    };
  },
};

2. Register it in src/server.ts:

import { myTool } from "./tools/my-tool.js";

const tools: ToolDefinition[] = [
  // ... existing tools
  myTool,
];

3. Build and run:

npm run build && npm start

Transport Modes

stdio (default)

npm start
# or
npm run start:stdio

SSE (HTTP)

npm run start:sse
# or
MCP_PORT=3001 node dist/index.js --transport=sse

The SSE endpoint will be available at http://localhost:3001/sse.

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

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

Claude Code

claude mcp add mcp-blanko node /absolute/path/to/mcp-blanko/dist/index.js

Docker Deployment

Build and run with Docker Compose:

docker compose up -d

The SSE endpoint will be available at http://localhost:3001/sse. Put a reverse proxy (e.g., nginx, Caddy, Traefik) in front for HTTPS.

Or build and run manually:

docker build -t mcp-blanko .
docker run -d -p 3001:3001 mcp-blanko

Environment Variables

Variable	Default	Description
MCP_TRANSPORT	stdio	Transport mode: stdio or sse
MCP_PORT	3001	HTTP port for SSE transport
MCP_FILES_DIR	cwd	Base directory for the file operation tool

License

MIT