JinDaGe - mcp-confluent MCP Details

article

README

🚀 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的新类：
1. 实现基类的handle方法。
2. 实现基类的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

mcp-confluent