AI导哈

MCP服务器模板

用于创建与Claude Desktop和其他MCP兼容客户端集成的MCP服务器的启动模板。

  • by iptracej-education
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 iptracej-education/mcp-server-template

使用说明

MCP服务器模板

用于创建与Claude Desktop和其他MCP兼容客户端集成的模型上下文协议（MCP）服务器的启动模板。

有关详细信息，请查看Anthroic mcp文档 https://docs.anthropic.com/en/docs/mcp

特性

  • 标准运输实施，包括Claude Desktop集成
  • 具有内置和自定义工具的可配置工具系统
  • 基于JSON的配置，带有环境变量覆盖
  • Docker支持容器化部署
  • 全面的日志记录和错误处理
  • TypeScript就绪结构
  • 常见操作示例工具

快速开始

安装

# Clone the template
git clone https://github.com/yourusername/mcp-server-template.git
cd mcp-server-template

# Install dependencies
npm install

# Run in development mode
npm run dev

配置

创建一个 config.json 项目根目录中的文件：

{
  "serverName": "my-mcp-server",
  "version": "1.0.0",
  "debug": true,
  "dataDir": "./data",
  "outputDir": "./output",
  "tools": {
    "enabled": true,
    "customToolsDir": "./custom-tools"
  }
}

Claude桌面集成

添加到您的Claude Desktop配置(claude_desktop_config.json):

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

项目结构

mcp-server-template/
├── src/
│   ├── server/          # Core server implementation
│   │   └── index.js     # Main server entry point
│   ├── config/          # Configuration management
│   │   └── config-loader.js
│   ├── tools/           # Tool system
│   │   └── tool-registry.js
│   └── generator/       # Template generator (optional)
├── examples/            # Example implementations
│   ├── custom-tool.js   # Example custom tool
│   └── docker/          # Docker configuration
├── tests/               # Test suite
├── docs/                # Documentation
├── config.json          # Default configuration
└── package.json

创建自定义工具

在中创建新工具 custom-tools 目录：

// custom-tools/my-tool.js
export default {
  name: 'my_custom_tool',
  description: 'Description of what this tool does',
  inputSchema: {
    type: 'object',
    properties: {
      param1: {
        type: 'string',
        description: 'First parameter'
      },
      param2: {
        type: 'number',
        description: 'Second parameter'
      }
    },
    required: ['param1']
  },
  handler: async (args) => {
    // Tool implementation
    const result = await doSomething(args.param1, args.param2);
    return {
      success: true,
      result: result
    };
  }
};

内置工具

该模板包括几个内置工具：

  • list_items -列出所有具有可选筛选的项目
  • add_item -向系统添加新项目
  • remove_item -按ID删除项目
  • search_items -使用高级查询搜索项目
  • get_status -获取系统状态和统计信息

环境变量

使用环境变量覆盖配置：

  • MCP_SERVER_NAME -服务器名称
  • MCP_VERSION -服务器版本
  • MCP_DEBUG -启用调试日志记录
  • MCP_DATA_DIR -数据目录路径
  • MCP_OUTPUT_DIR -输出目录路径
  • MCP_CONFIG_PATH -自定义配置文件路径

Docker部署

使用Docker构建和运行：

# Build image
docker build -t my-mcp-server .

# Run container
docker run -d \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/output:/app/output \
  --name my-mcp-server \
  my-mcp-server

发展

运行测试

npm test

代码检查

npm run lint

生产大楼

npm run build

api参考

工具架构

所有工具都遵循此模式：

{
  name: string,           // Unique tool identifier
  description: string,    // Human-readable description
  inputSchema: {         // JSON Schema for parameters
    type: 'object',
    properties: {},
    required: []
  },
  handler: async function // Tool implementation
}

配置架构

{
  serverName: string,     // Server identifier
  version: string,        // Server version
  debug: boolean,         // Enable debug logging
  dataDir: string,        // Data storage directory
  outputDir: string,      // Output directory
  maxFileSize: number,    // Maximum file size in bytes
  timeout: number,        // Request timeout in ms
  tools: {
    enabled: boolean,     // Enable tool system
    customToolsDir: string // Custom tools directory
  }
}

扩展模板

添加新功能

  1. 在中创建功能模块 src/features/
  2. 在服务器上注册 src/server/index.js
  3. 向添加配置选项 config-loader.js
  4. 自述文件和API参考文件

创建特定于域的服务器

  1. 分叉此模板
  2. 用特定于域的工具替换示例工具
  3. 自定义配置模式
  4. 更新文档
  5. 作为独立MCP服务器部署

故障排除

常见问题

服务器未启动：

  • 检查Node.js版本（>=16.0.0）
  • 验证配置文件语法
  • 检查文件权限

工具未加载：

  • 验证工具文件导出默认对象
  • 检查工具架构有效性
  • 查看调试日志中的错误

Claude桌面集成：

  • 确保配置中的路径正确
  • 检查服务器进程是否正在运行
  • 查看克劳德桌面日志

贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支
  3. 为新功能添加测试
  4. 更新文档
  5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

致谢

为模型上下文协议生态系统构建，使AI助手能够通过标准化的界面与外部系统进行交互。

相关 MCP