# 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

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

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
);

npm start

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

MCP_SERVER_TRANSPORT=http npm start

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

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

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

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

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

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

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

# 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