MCP Base Server

Um modelo base para criar novos servidores MCP, projetado para implantação fácil em contêineres com Docker.

GitHubExperimente este MCPPatrocinado

Documentação

MCP Base Server

README em inglês

Este é um modelo base para criação de servidores MCP (Model Context Protocol).

Recursos

  • Implementação de servidor MCP baseada em TypeScript
  • Arquitetura modular de ferramentas
  • Validação integrada com esquemas Zod
  • Implementação de ferramentas de exemplo
  • Ambiente de testes Vitest
  • Tratamento abrangente de erros
  • Modelo de desenvolvimento rápido de servidores MCP

Requisitos

  • Docker
  • Docker Compose (opcional)

Instalação

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

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

Como usar

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

Ambiente de desenvolvimento (para desenvolvimento local)

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

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

# テスト実行
npm test

# ビルド
npm run build

Configuração do cliente MCP

Claude Desktop

  1. Edite o arquivo de configuração do Claude Desktop:

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

  1. Adicione a seguinte configuração:

Ao usar Docker (recomendado)

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

Ao usar build local

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

Configuração no ambiente de desenvolvimento

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

Outros clientes MCP

Pode ser usado a partir de qualquer cliente MCP que suporte transporte stdio:

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

Arquitetura

O projeto segue uma arquitetura modular:

  • src/index.ts - Ponto de entrada principal do servidor
  • src/core/tool-handler.ts - Lógica principal de execução das ferramentas
  • src/tools/ - Implementações de ferramentas organizadas por categoria
  • src/tools/registry.ts - Registro e descoberta de ferramentas
  • src/types/ - Definições de tipos TypeScript

Adicionando novas ferramentas

  1. Crie um novo arquivo de ferramenta em src/tools/[category]/[tool-name].ts
  2. Defina o esquema da ferramenta, tipos de entrada/saída e implementação
  3. Exporte toolDefinition para registro
  4. Adicione a ferramenta em src/tools/registry.ts
  5. Atualize o manipulador de ferramentas em src/core/tool-handler.ts

Modelo de implementação de ferramentas

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

Guia de personalização

1. Alterar o nome do projeto

Atualize package.json e src/index.ts com o nome do projeto:

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

2. Adicionar clientes personalizados

Adicione clientes personalizados em 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. Variáveis de ambiente

Adicione o tratamento de variáveis de ambiente conforme necessário:

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

Scripts disponíveis

  • npm run build - Compila TypeScript para JavaScript
  • npm run start - Inicia o servidor de produção
  • npm run dev - Inicia o servidor de desenvolvimento com ts-node
  • npm run lint - Executa o ESLint
  • npm run typecheck - Executa a verificação de tipos TypeScript
  • npm test - Executa os testes
  • npm run test:watch - Executa os testes em modo de observação
  • npm run test:coverage - Executa os testes com relatório de cobertura
  • npm run docker:build - Constrói a imagem Docker
  • npm run docker:run - Executa o contêiner Docker
  • npm run docker:dev - Inicia o ambiente de desenvolvimento com Docker Compose

Estrutura do projeto

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                 # このファイル

Contribuição

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Adicione alterações com testes
  4. Execute lint e verificação de tipos
  5. Envie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para mais detalhes.