Model Context Protocol (MCP) server implementation specialist for Claude Desktop integration. Handles TypeScript/Node.js server scaffolding, endpoint creation, telemetry setup, npx distribution, and comprehensive documentation. Follows MCP specification and best practices for production-grade server deployment.
npxskills add vuralserhat86/antigravity-agentic-skills--skill mcp_server_developerLoading…
Expert implementation of Model Context Protocol (MCP) servers for Claude Desktop integration. This skill provides comprehensive guidance for building production-ready MCP servers with TypeScript, including architecture design, endpoint implementation, database integration, telemetry tracking, and distribution via npx.
Initialize TypeScript Project
npm init -y
npm install --save-dev typescript @types/node
npx tsc --init
MCP Server Setup
npm install @modelcontextprotocol/sdksrc/index.ts)Type Definitions
interface MCPServer {
name: string;
version: string;
resources: Resource[];
tools: Tool[];
}
interface Resource {
uri: string;
name: string;
description: string;
mimeType?: string;
}
interface Tool {
name: string;
description: string;
inputSchema: JSONSchema;
}
Database Schema
CREATE TABLE mental_models (
id TEXT PRIMARY KEY,
code TEXT UNIQUE NOT NULL,
transformation_class TEXT NOT NULL,
name TEXT NOT NULL,
description TEXT,
use_cases JSON,
difficulty_tier INTEGER,
prerequisites JSON,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE VIRTUAL TABLE models_fts USING fts5(
code, name, description, use_cases
);
Endpoint Implementation
Transformation Logic
Quick Start Guide (5-minute setup)
# Quick Start
1. Install via npx:
```bash
npx @hummbl/mcp-server
Configure Claude Desktop:
Add to claude_desktop_config.json:
{
"mcpServers": {
"hummbl": {
"command": "npx",
"args": ["@hummbl/mcp-server"]
}
}
}
Test in Claude: "Use the perspective transformation on this problem: [your problem]"
Runnable Examples
Troubleshooting Guide
NPX Setup
{
"name": "@hummbl/mcp-server",
"version": "1.0.0",
"bin": {
"hummbl-mcp": "./dist/index.js"
},
"files": ["dist", "README.md", "LICENSE"],
"publishConfig": {
"access": "public"
}
}
CI/CD Pipeline
Beta Testing
interface TelemetryEvent {
event_name: 'mcp_install' | 'mcp_success_run' | 'api_call' | 'doc_view';
user_id: string; // Anonymized hash
ts: string; // ISO 8601
meta: {
client?: string; // Claude Desktop version
version?: string; // MCP server version
model?: string; // e.g., "CO4"
lat_ms?: number; // Latency in milliseconds
endpoint?: string; // Endpoint called
status?: number; // HTTP-style status code
};
}
npm audit)Solution: Verify stdio transport is properly initialized and JSON-RPC responses are formatted correctly.
Solution: Add database indexes, implement caching, or optimize query complexity.
Solution: Test with cross-platform paths, avoid shell-specific commands, use cross-env for environment variables.
Solution: Follow semantic versioning strictly, maintain backwards compatibility, provide migration guides.
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
const server = new Server({
name: 'hummbl-mcp-server',
version: '1.0.0',
}, {
capabilities: {
resources: {},
tools: {},
},
});
// Register resource: List mental models
server.setRequestHandler('resources/list', async () => ({
resources: [
{
uri: 'hummbl://models',
name: 'Mental Models',
description: 'BASE120 mental model collection',
mimeType: 'application/json',
},
],
}));
// Register tool: Analyze with perspective transformation
server.setRequestHandler('tools/call', async (request) => {
if (request.params.name === 'analyze-perspective') {
const { text } = request.params.arguments;
// Transformation logic here
return {
content: [{
type: 'text',
text: `Perspective analysis: ${text}`,
}],
};
}
});
// Start server
const transport = new StdioServerTransport();
await server.connect(transport);
import Database from 'better-sqlite3';
const db = new Database('hummbl.db');
// Initialize schema
db.exec(`
CREATE TABLE IF NOT EXISTS mental_models (
id TEXT PRIMARY KEY,
code TEXT UNIQUE NOT NULL,
transformation_class TEXT NOT NULL,
name TEXT NOT NULL,
description TEXT
);
CREATE INDEX IF NOT EXISTS idx_transformation
ON mental_models(transformation_class);
`);
// Query with prepared statement
const getModelsByTransformation = db.prepare(`
SELECT * FROM mental_models
WHERE transformation_class = ?
ORDER BY code
`);
const perspectiveModels = getModelsByTransformation.all('P');
function logTelemetry(event: TelemetryEvent) {
const logEntry = {
...event,
ts: new Date().toISOString(),
};
// Log to console (development)
if (process.env.NODE_ENV === 'development') {
console.log(JSON.stringify(logEntry));
}
// Send to analytics service (production)
if (process.env.NODE_ENV === 'production') {
// TODO: Send to analytics endpoint
}
}
// Usage
logTelemetry({
event_name: 'api_call',
user_id: hashUserId(userId),
ts: new Date().toISOString(),
meta: {
endpoint: '/tools/analyze-perspective',
lat_ms: 245,
status: 200,
},
});
Phase 0 is successful when:
npx @hummbl/mcp-server runs cleanly on any machinePhase 0 fails if:
Kaynak: Anthropic MCP SDK Best Practices
npm init ve TypeScript config ayarlarını yap.onerror handler ile güvenli hale getir.nodemon veya watch modunu kullan.npx @modelcontextprotocol/inspector ile canlı debug yap.npm'e veya npx ile çalışacak şekilde publish et.claude_desktop_config.json örneğini ekle.| Aşama | Doğrulama |
|---|---|
| 1 | Server hatasız kapanıp (graceful shutdown) yeniden başlıyor mu? |
| 2 | list_tools çağrısı <100ms içinde cevap veriyor mu? |
| 3 | Dokümantasyon "Copy-Paste" ile çalıştırılabiliyor mu? |
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).