MCP Base Server

Una plantilla base para crear nuevos servidores MCP, diseñada para una implementación contenerizada fácil con Docker.

GitHubPrueba este MCPPatrocinado

Documentación

MCP Base Server

README en inglés

Esta es una plantilla base para crear servidores MCP (Model Context Protocol).

Características

  • Implementación de servidor MCP basada en TypeScript
  • Arquitectura de herramientas modular
  • Validación integrada mediante esquemas Zod
  • Implementación de herramientas de ejemplo
  • Entorno de pruebas con Vitest
  • Manejo integral de errores
  • Plantilla de desarrollo rápido de servidores MCP

Requisitos

  • Docker
  • Docker Compose (opcional)

Instalación

# リポジトリをクローン
git clone <repository-url>
cd mcp-base

# Dockerイメージをビルド
docker build -t mcp-base .

Uso

Docker (recomendado)

# 基本実行
docker run --rm -i mcp-base

# 環境変数を指定して実行
docker run --rm -i -e API_KEY=your_api_key_here mcp-base

# Docker Composeを使用
docker-compose up --build

Entorno de desarrollo (para desarrollo local)

# 依存関係をインストール
npm install

# 開発モードで開始
npm run dev

# テスト実行
npm test

# ビルド
npm run build

Configuración del cliente MCP

Claude Desktop

  1. Edite el archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

  1. Agregue la siguiente configuración:

Al usar Docker (recomendado)

{
  "mcpServers": {
    "mcp-base": {
      "command": "docker",
      "args": [
        "run", 
        "--rm", 
        "-i",
        "mcp-base"
      ]
    }
  }
}

Al usar una compilación local

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

Configuración en el entorno de desarrollo

{
  "mcpServers": {
    "mcp-base-dev": {
      "command": "npx",
      "args": ["ts-node", "/path/to/mcp-base/src/index.ts"],
      "cwd": "/path/to/mcp-base"
    }
  }
}

Otros clientes MCP

Se puede usar desde cualquier cliente MCP que admita transporte stdio:

# Dockerで直接実行
docker run --rm -i mcp-base

Arquitectura

El proyecto sigue una arquitectura modular:

  • src/index.ts - Punto de entrada principal del servidor
  • src/core/tool-handler.ts - Lógica central de ejecución de herramientas
  • src/tools/ - Implementaciones de herramientas organizadas por categoría
  • src/tools/registry.ts - Registro y descubrimiento de herramientas
  • src/types/ - Definiciones de tipos TypeScript

Agregar nuevas herramientas

  1. Cree un nuevo archivo de herramienta en src/tools/[category]/[tool-name].ts
  2. Defina el esquema de la herramienta, los tipos de entrada/salida y la implementación
  3. Exporte toolDefinition para el registro
  4. Agregue la herramienta a src/tools/registry.ts
  5. Actualice el manejador de herramientas en src/core/tool-handler.ts

Plantilla de implementación de herramientas

import { z } from 'zod';
import { ToolDefinition } from '../../types/mcp.js';

// 入力スキーマ定義
export const MyToolInputSchema = z.object({
  parameter: z.string().describe('パラメータの説明'),
  optionalParam: z.boolean().optional().default(false)
}).strict();

export type MyToolInput = z.infer<typeof MyToolInputSchema>;

// MCPツール定義
export const toolDefinition: ToolDefinition = {
  name: 'my_tool',
  description: 'ツールの機能説明',
  inputSchema: {
    type: 'object' as const,
    properties: {
      parameter: {
        type: 'string',
        description: 'パラメータの説明'
      },
      optionalParam: {
        type: 'boolean',
        description: 'オプションパラメータの説明',
        default: false
      }
    },
    required: ['parameter'],
    additionalProperties: false
  }
};

// 出力スキーマ定義
export const MyToolOutputSchema = z.object({
  result: z.string(),
  timestamp: z.string().optional()
});

export type MyToolOutput = z.infer<typeof MyToolOutputSchema>;

// ツール実装
export async function myTool(input: MyToolInput): Promise<MyToolOutput> {
  return {
    result: `処理結果: ${input.parameter}`,
    timestamp: new Date().toISOString()
  };
}

Guía de personalización

1. Cambiar el nombre del proyecto

Actualice package.json y src/index.ts con el nombre de su proyecto:

// src/index.ts
this.server = new Server({
  name: 'your-mcp-server',
  version: '1.0.0',
});

2. Agregar clientes personalizados

Agregue clientes personalizados en src/core/tool-handler.ts:

export class ToolHandler {
  private customClient: CustomClient | null = null;

  private async ensureCustomClient(): Promise<CustomClient> {
    if (!this.customClient) {
      const apiKey = process.env.API_KEY;
      if (!apiKey) {
        throw new McpError(
          ErrorCode.InvalidRequest,
          'API_KEY環境変数が設定されていません'
        );
      }
      this.customClient = new CustomClient(apiKey);
    }
    return this.customClient;
  }
}

3. Variables de entorno

Agregue el manejo de variables de entorno según sea necesario:

# 環境変数の例
export API_KEY="your_api_key_here"
export LOG_LEVEL="info"

Scripts disponibles

  • npm run build - Compila TypeScript a JavaScript
  • npm run start - Inicia el servidor de producción
  • npm run dev - Inicia el servidor de desarrollo con ts-node
  • npm run lint - Ejecuta ESLint
  • npm run typecheck - Ejecuta la verificación de tipos TypeScript
  • npm test - Ejecuta las pruebas
  • npm run test:watch - Ejecuta las pruebas en modo de vigilancia
  • npm run test:coverage - Ejecuta las pruebas con informe de cobertura
  • npm run docker:build - Compila la imagen Docker
  • npm run docker:run - Ejecuta el contenedor Docker
  • npm run docker:dev - Inicia el entorno de desarrollo con Docker Compose

Estructura del proyecto

mcp-base/
├── src/
│   ├── core/
│   │   └── tool-handler.ts    # コアツール実行ロジック
│   ├── tools/
│   │   ├── registry.ts        # ツール登録
│   │   └── example/
│   │       └── example-tool.ts # サンプルツール実装
│   ├── types/
│   │   └── mcp.ts            # 型定義
│   └── index.ts              # メインサーバーエントリーポイント
├── dist/                     # コンパイル済みJavaScript出力
├── package.json              # プロジェクト依存関係とスクリプト
├── tsconfig.json             # TypeScript設定
├── vitest.config.ts          # テスト設定
├── CLAUDE.md                 # 開発ドキュメント
└── README.md                 # このファイル

Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Agregue cambios con pruebas
  4. Ejecute lint y verificación de tipos
  5. Envíe una solicitud de extracción

Licencia

Licencia MIT: consulte el archivo LICENSE para más detalles.