🚀 MCP服务器开发指南
本指南旨在帮助开发者搭建和运行MCP服务器，详细介绍了环境变量配置、项目结构、构建与运行步骤、测试方法以及贡献方式。
🚀 快速开始
要快速启动MCP服务器，需完成环境变量配置、安装依赖、构建项目并启动服务器。以下是简要步骤：
- 配置环境变量，可参考
.env文件示例。 - 安装项目依赖：
npm install - 进行生产构建：
npm run build - 启动服务器：
npm run start
✨ 主要特性
- 环境变量管理：通过配置关键环境变量，实现身份验证和目标集群指定。
- 清晰的项目结构：源代码、编译输出、配置文件等各部分组织明确。
- 灵活的构建与运行方式：支持开发模式和生产构建，方便不同场景使用。
- 丰富的测试手段：可使用MCP Inspector进行测试，也能添加新工具进行功能扩展。
📦 安装指南
安装依赖
在项目根目录下执行以下命令安装项目所需的依赖：
npm install
开发模式
若要在开发过程中实时监控代码变更并自动重新构建，可执行以下命令：
npm run dev
此命令会将TypeScript代码编译为JavaScript，并在检测到src/目录中的更改时自动重新构建。
生产构建
进行一次性编译，将TypeScript代码转换为JavaScript，可执行以下命令：
npm run build
启动服务器
完成构建后，启动MCP服务器，执行以下命令：
npm run start
💻 使用示例
基础用法
配置环境变量
以下是运行MCP服务器所需的关键环境变量：
| 属性 | 详情 |
|---|---|
MCP_API_KEY |
用于身份验证的API密钥 |
MCP_API_SECRET_KEY |
与API密钥对应的私有秘钥 |
MCP_CLUSTER_ID |
目标集群的唯一标识符 |
CONFLUENT_CLOUD_ENDPOINT |
Confluent Cloud服务的.endpoint地址 |
项目结构
/
├── src/ # 源代码目录
│ ├── confluent/ # Confluent相关代码（API客户端等）
│ ├── tools/ # 工具实现（每个工具单独文件）
│ ├── index.ts # 服务器主入口点
│ └── ... # 其他服务器逻辑、公用事业等
├── dist/ # 编译输出目录（TypeScript转为JavaScript）
├── openapi.json # Confluent Cloud的OpenAPI规范
├── .env # 环境变量配置文件（示例 - 应该复制并填写）
├── README.md # 本文件
└── package.json # Node.js项目元数据和依赖项
高级用法
使用MCP Inspector测试
为了测试MCP服务器，可以使用MCP Inspector，这是一个交互式开发工具，用于测试和调试MCP服务器。
# 确保已经以开发或构建模式运行过项目
npx @modelcontextprotocol/inspector node $PATH_TO_PROJECT/dist/index.js --env-file $PATH_TO_PROJECT/.env
添加新工具
- 在枚举类
ToolName中添加一个新的枚举值。 - 将新的工具添加到
ToolFactory类的句柄映射中。 - 创建一个新的文件，导出一个继承自
BaseToolHandler的新类：- 实现基类的
handle方法。 - 实现基类的
getToolConfig方法。
- 实现基类的
- 完成后，在
index.ts文件中的enabledTools集合中添加新的工具。
类型生成
# 注意：由于版本7.5.2中存在一个与allOf和required相关的bug，需要使用--empty-objects-unknown标志来避免它
npx openapi-typescript ./openapi.json -o ./src/confluent/openapi-schema.d.ts --empty-objects-unknown
📚 详细文档
贡献指南
欢迎提交问题报告和技术反馈，请以GitHub Issues的形式提出。有关贡献指南，请参阅CONTRIBUTING.md