MCP 服务器

MCP Server Template

A production-ready TypeScript template for building MCP servers with dual transport support (stdio/HTTP), OAuth 2.1 foundations, SQLite caching, observability, and security features including PII sanitization and rate limiting.

README

MCP Server Template

A production-ready template for building Model Context Protocol (MCP) servers with TypeScript.

Features

MCP SDK 1.24.3 - Latest SDK with 2025-11-25 spec support
Dual Transport - Stdio (Claude Desktop) and HTTP (cloud deployment)
OAuth 2.1 Foundations - Protected resource metadata, bearer token structure
SQLite Caching - TTL-based caching with sql.js (WebAssembly)
Observability - Sentry error tracking + OpenTelemetry tracing
Security - PII sanitization, rate limiting, DNS rebinding protection
Type Safety - Strict TypeScript with Zod validation

Quick Start

# Clone and install
git clone <this-repo> my-mcp-server
cd my-mcp-server
npm install

# Development mode (hot reload)
npm run dev

# Build and run
npm run build
npm start

# Test with MCP Inspector
npm run inspector

Project Structure

src/
├── index.ts              # CLI entry point
├── server.ts             # MCP server implementation
├── instrumentation.ts    # Sentry + OpenTelemetry setup
├── config/
│   └── index.ts          # Environment configuration
├── db/
│   ├── database.ts       # SQLite connection (sql.js)
│   └── cache.ts          # TTL-based caching
├── tools/
│   ├── registry.ts       # Tool registration pattern
│   └── examples.ts       # Example tool implementations
├── transport/
│   └── http-transport.ts # HTTP with OAuth foundations
├── shared/
│   ├── logger.ts         # Structured logging
│   ├── errors.ts         # Custom error classes
│   ├── rate-limiter.ts   # Per-source rate limiting
│   ├── pii-sanitizer.ts  # PII detection/removal
│   └── tracing.ts        # OpenTelemetry utilities
└── types/
    └── index.ts          # TypeScript type definitions

Configuration

Environment variables (prefix with MCP_SERVER_):

Variable	Default	Description
`MCP_SERVER_NAME`	`mcp-server-template`	Server name
`MCP_SERVER_VERSION`	`0.1.0`	Server version
`MCP_SERVER_LOG_LEVEL`	`info`	Log level: debug, info, warning, error
`MCP_SERVER_DB_PATH`	`.data/cache.db`	SQLite database path
`MCP_SERVER_CACHE_ENABLED`	`true`	Enable/disable caching
`MCP_SERVER_CACHE_TTL`	`3600`	Default cache TTL (seconds)
`MCP_SERVER_TIMEOUT`	`30000`	Request timeout (ms)
`MCP_SERVER_TRANSPORT`	`stdio`	Transport: `stdio` or `http`
`MCP_SERVER_PORT`	`3000`	HTTP port (when transport=http)
`MCP_SERVER_HOST`	`127.0.0.1`	HTTP host (when transport=http)
`MCP_SERVER_SENTRY_DSN`	-	Sentry DSN for error tracking
`OTEL_ENABLED`	`false`	Enable OpenTelemetry tracing
`OTEL_EXPORTER_OTLP_ENDPOINT`	-	OTLP collector endpoint
`MCP_SERVER_DEBUG`	`false`	Debug mode (skips auth)

Creating Tools

Tools are registered with the ToolRegistry using Zod schemas:

import { z } from 'zod';
import { getToolRegistry } from './tools/registry.js';

// Define input schema
const MyToolInputSchema = z.object({
  query: z.string().min(1).describe('Search query'),
  limit: z.number().positive().optional().default(10),
});

type MyToolInput = z.infer<typeof MyToolInputSchema>;

// Implement handler
async function myToolHandler(input: MyToolInput) {
  // Your implementation here
  return {
    success: true,
    data: { results: [] },
  };
}

// Register tool
const registry = getToolRegistry();
registry.register(
  'my_tool',
  'Description of what this tool does',
  MyToolInputSchema,
  myToolHandler
);

Transport Modes

Stdio (Default)

For Claude Desktop and local integrations:

npm start

Add to Claude Desktop config:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/dist/index.js"]
    }
  }
}

HTTP

For cloud deployment:

MCP_SERVER_TRANSPORT=http npm start

Endpoints:

GET /health - Health check
GET /.well-known/mcp - MCP server metadata
GET /.well-known/oauth-protected-resource - OAuth metadata (RFC 9728)
GET /mcp - SSE stream for server events
POST /mcp - JSON-RPC requests
DELETE /mcp - Close session

Security Features

PII Sanitization

Automatically detects and masks sensitive data:

import { sanitizePii } from './shared/pii-sanitizer.js';

const safe = sanitizePii('Contact: user@example.com');
// Output: "Contact: [EMAIL]"

Rate Limiting

Per-source rate limiting with exponential backoff:

import { getRateLimiter } from './shared/rate-limiter.js';

const limiter = getRateLimiter();
limiter.configure('external-api', {
  requestsPerWindow: 100,
  windowMs: 60000,
});

await limiter.waitForSlot('external-api');
// Make request...

DNS Rebinding Protection

HTTP transport validates Host headers against allowlist.

Observability

Sentry

Error tracking with PII filtering:

MCP_SERVER_SENTRY_DSN=https://xxx@sentry.io/xxx npm start

OpenTelemetry

Distributed tracing:

OTEL_ENABLED=true \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
npm start

Use tracing utilities:

import { withSpan, createApiSpan } from './shared/tracing.js';

const result = await withSpan('my-operation', async (span) => {
  span.setAttribute('custom.attr', 'value');
  return doWork();
});

Development

# Type check
npm run check

# Lint
npm run lint
npm run lint:fix

# Format
npm run format

# Test
npm test
npm run test:coverage

# Validate (all checks)
npm run validate

MCP 2025-11-25 Spec Compliance

Feature	Status
Tools	✅ Implemented
Resources	📝 Scaffolded
Prompts	📝 Scaffolded
Streamable HTTP	✅ Implemented
.well-known/mcp	✅ Implemented
OAuth 2.1 Foundations	✅ Scaffolded
Tasks	❌ Not yet
Elicitation	❌ Not yet

OAuth 2.1 Implementation

The template includes foundations for OAuth 2.1 per the MCP spec:

Protected Resource Metadata (RFC 9728) at /.well-known/oauth-protected-resource
Bearer token middleware structure (implement JWT validation)
WWW-Authenticate headers with resource_metadata reference
Scope checking structure for tool authorization

To complete OAuth integration: