yuce-mcp-api-bridge

v1.0.6

Published

7 months ago

将数据魔方 API Controllers 开放为 MCP 服务的桥接包

0High
0Medium
0Low

yucekj

mcp model-context-protocol api bridge yuce cube

MCP API Bridge 完整使用指南

🎯 概述

yuce-mcp-api-bridge 是一个将数据魔方 API Controllers 开放为 MCP (Model Context Protocol) 服务的桥接工具。它能够将现有的 API 控制器无缝转换为 AI 助手可以调用的工具，让您的 AI 助手能够直接与数据魔方平台进行交互。

核心价值

🔗 AI 集成: 让 Claude、GPT 等 AI 助手直接调用数据魔方 API
🛠️ 零配置: 基于现有 Controller 自动生成 MCP 工具
🎯 选择性暴露: 精确控制哪些 API 对 AI 可见
⚡ 开箱即用: 支持命令行快速启动和配置文件管理
📝 类型安全: 完整的 TypeScript 支持和错误处理

🏗️ 架构设计

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Assistant  │────│  MCP API Bridge  │────│  数据魔方 API    │
│  (Claude/GPT)   │    │                  │    │  Controllers    │
└─────────────────┘    └──────────────────┘    └─────────────────┘

数据流向:

AI 助手发送工具调用请求
MCP Bridge 解析请求并映射到对应的 Controller 方法
调用数据魔方 API 并返回结果
将结果格式化后返回给 AI 助手

🚀 快速开始

环境要求

Node.js >= 18.0.0
pnpm >= 8.0.0
数据魔方 API 访问权限

1. 安装和构建

# 在项目根目录
npm install yuce-mcp-api-bridge -g

2. 第一次运行

# 查看可用的 Controllers
yuce-mcp-api-bridge list-controllers

# 快速启动 - 暴露用户管理相关接口
yuce-mcp-api-bridge serve \
  --controllers UserController WorkspaceController \
  --api-base-url https://your-domain.com/api \
  --access-token your-access-token \
  --verbose

3. 验证安装

# 检查版本
yuce-mcp-api-bridge --version

# 检查配置状态
yuce-mcp-api-bridge status

🎛️ 命令行工具详解

`serve` - 启动 MCP 服务器

这是最重要的命令，用于启动 MCP 服务器：

yuce-mcp-api-bridge serve [options]

选项说明:

| 选项 | 描述 | 示例 | | ------------------------ | ---------------------- | -------------------------------------------------- | | -c, --config <path> | 指定配置文件路径 | --config ./my-config.json | | --controllers <list> | 启用的 Controller 列表 | --controllers UserController WorkspaceController | | --api-base-url <url> | API 基础 URL | --api-base-url https://api.example.com | | --access-token <token> | API 访问令牌 | --access-token abc123... | | --timeout <ms> | API 请求超时时间 | --timeout 30000 | | -p, --port <number> | HTTP 模式端口 | --port 3000 | | -h, --host <host> | HTTP 模式主机 | --host 0.0.0.0 | | -t, --transport <type> | 传输类型 | --transport stdio (默认) | | --verbose | 详细输出模式 | --verbose |

使用示例:

# 基础用法
yuce-mcp-api-bridge serve --controllers UserController --api-base-url https://api.example.com --access-token your-token

# 使用配置文件
yuce-mcp-api-bridge serve --config etl-config.json

# HTTP 模式 (适用于调试)
yuce-mcp-api-bridge serve --controllers UserController --port 3000 --transport http

# 详细模式 (显示调试信息)
yuce-mcp-api-bridge serve --controllers UserController --verbose

`init` - 生成配置文件

生成标准的配置文件模板：

yuce-mcp-api-bridge init [options]

选项:

-o, --output <path>: 输出文件路径 (默认: mcp-config.json)
--controllers <list>: 预配置的 Controller 列表
--api-base-url <url>: API 基础 URL
--access-token <token>: 访问令牌

示例:

# 生成基本配置
yuce-mcp-api-bridge init

# 为特定 Controllers 生成配置
yuce-mcp-api-bridge init \
  --controllers UserController ReportFormController AssetSearchController \
  --api-base-url https://api.example.com \
  --access-token your-token \
  --output production-config.json

`list-controllers` - 列出可用 Controllers

查看所有可用的 API Controllers：

yuce-mcp-api-bridge list-controllers

输出示例：

可用的 Controllers:
✓ UserController - 用户管理相关接口
✓ WorkspaceController - 工作空间管理
✓ ReportFormController - 报表管理
✓ AssetSearchController - 资产搜索
...

`status` - 检查配置状态

检查配置文件的有效性和服务状态：

yuce-mcp-api-bridge status [--config <path>]

⚙️ 配置管理

配置文件结构

interface McpServiceConfig {
  /** 服务基本信息 */
  name: string; // 服务名称
  version: string; // 版本号
  description?: string; // 服务描述

  /** API 连接配置 */
  api: {
    baseURL: string; // API 基础 URL
    accessToken: string; // 访问令牌
    timeout?: number; // 超时时间(ms)，默认 30000
  };

  /** 工具配置列表 */
  tools: McpToolConfig[];
}

interface McpToolConfig {
  name: string; // 工具名称 (唯一标识)
  description: string; // 工具描述 (AI 可见)
  controller: string; // Controller 类名
  method: string; // Controller 方法名
  enabled?: boolean; // 是否启用，默认 true
}

完整配置示例

{
  "name": "yuce-data-platform-mcp",
  "version": "1.0.0",
  "description": "数据魔方平台 MCP 接口服务",
  "api": {
    "baseURL": "https://api.example.com",
    "accessToken": "your-access-token-here",
    "timeout": 30000
  },
  "tools": [
    {
      "name": "user_get_info",
      "description": "获取当前用户基本信息",
      "controller": "UserController",
      "method": "getUserInfoUsingGET",
      "enabled": true
    },
    {
      "name": "workspace_list",
      "description": "获取用户有权限的工作空间列表",
      "controller": "WorkspaceController",
      "method": "listWorkspacesUsingGET",
      "enabled": true
    },
    {
      "name": "asset_search",
      "description": "在数据平台中搜索数据资产",
      "controller": "AssetSearchController",
      "method": "searchAssetsUsingPOST",
      "enabled": true
    }
  ]
}

预设配置模板

数据分析师配置

{
  "name": "data-analyst-mcp",
  "description": "数据分析师专用工具集",
  "tools": [
    {
      "name": "search_datasets",
      "description": "搜索可用数据集",
      "controller": "AssetSearchController",
      "method": "searchAssetsUsingPOST"
    },
    {
      "name": "list_reports",
      "description": "获取报表列表",
      "controller": "ReportFormController",
      "method": "listReportFormsUsingGET"
    },
    {
      "name": "get_report_detail",
      "description": "获取报表详细信息",
      "controller": "ReportFormController",
      "method": "getReportFormDetailUsingGET"
    }
  ]
}

系统管理员配置

{
  "name": "admin-mcp",
  "description": "系统管理员工具集",
  "tools": [
    {
      "name": "manage_users",
      "description": "用户管理",
      "controller": "UserController",
      "method": "getUserInfoUsingGET"
    },
    {
      "name": "manage_workspaces",
      "description": "工作空间管理",
      "controller": "WorkspaceController",
      "method": "listWorkspacesUsingGET"
    },
    {
      "name": "manage_departments",
      "description": "部门管理",
      "controller": "DepartmentController",
      "method": "getDepartmentsUsingGET"
    }
  ]
}

🔌 集成指南

与 Claude Desktop 集成

找到 Claude Desktop 配置文件:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
添加 MCP 服务配置:

{
  "mcpServers": {
    "yuce-data-platform": {
      "command": "yuce-mcp-api-bridge",
      "args": ["serve", "--config", "/path/to/your/config.json"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

重启 Claude Desktop 使配置生效

与其他 MCP 客户端集成

MCP API Bridge 遵循标准的 MCP 协议，可以与任何支持 MCP 的客户端集成：

# 通过 stdio 协议
yuce-mcp-api-bridge serve --config config.json

# 通过 HTTP 协议 (用于调试)
yuce-mcp-api-bridge serve --config config.json --transport http --port 3000

📋 支持的 Controllers

核心业务 Controllers

| Controller | 功能描述 | 主要方法 | | ---------------------- | ------------ | ------------------------ | | UserController | 用户管理 | getUserInfoUsingGET | | WorkspaceController | 工作空间管理 | listWorkspacesUsingGET | | DepartmentController | 部门管理 | getDepartmentsUsingGET |

数据分析 Controllers

| Controller | 功能描述 | 主要方法 | | --------------------------- | -------- | -------------------------------------------------------- | | AssetSearchController | 资产搜索 | searchAssetsUsingPOST | | ReportFormController | 报表管理 | listReportFormsUsingGET, getReportFormDetailUsingGET | | AnalysisProjectController | 分析项目 | listAnalysisProjectsUsingGET | | MetricsDocumentController | 指标文档 | getMetricsDocumentUsingGET |

ETL 和数据处理 Controllers

| Controller | 功能描述 | 主要方法 | | ---------------------- | ---------- | -------------------------------- | | EtlDevelopController | ETL 开发 | getAllProjectWithNodesUsingGET | | TaskDagController | 任务流管理 | listTaskDagsUsingGET | | WorkTableController | 工作表管理 | getWorkTableCacheDataUsingGET |

系统集成 Controllers

| Controller | 功能描述 | 主要方法 | | --------------------------------- | ------------ | ----------------------------------- | | ThirdPartyDataSourcesController | 第三方数据源 | listDataSourcesUsingGET | | UserPropertySyncController | 用户属性同步 | getUserPropertySyncConfigUsingGET | | BaseShieldController | 基础防护 | getShieldConfigUsingGET |

🛠️ 开发指南

项目结构

apps/yuce-mcp-api-bridge/
├── src/
│   ├── types.ts              # TypeScript 类型定义
│   ├── controller-scanner.ts # Controller 自动扫描器
│   ├── mcp-server.ts         # MCP 服务器核心实现
│   ├── config.ts             # 配置文件管理
│   ├── api-config.ts         # API 连接配置
│   ├── cli.ts                # 命令行接口
│   └── index.ts              # 主入口文件
├── examples/                 # 使用示例
│   ├── basic-config.json     # 基础配置示例
│   ├── etl-config.json       # ETL 专用配置
│   ├── usage-examples.md     # 使用场景示例
│   └── complete-setup.md     # 完整部署指南
├── scripts/                  # 辅助脚本
├── dist/                     # 构建输出
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md

本地开发

# 开发模式启动 (支持热重载)
pnpm dev serve --controllers UserController --verbose

# 构建项目
pnpm build

# 启动构建后的版本
pnpm start serve --controllers UserController

# 清理构建产物
pnpm clean

# 运行测试
pnpm test:basic

调试技巧

使用详细模式:

yuce-mcp-api-bridge serve --controllers UserController --verbose

HTTP 模式调试:

# 启动 HTTP 服务器进行调试
yuce-mcp-api-bridge serve --controllers UserController --transport http --port 3000

# 然后可以使用 curl 测试
curl -X POST http://localhost:3000/tools/list

检查配置状态:

yuce-mcp-api-bridge status --config your-config.json

添加新 Controller 支持

确保 Controller 在 @ylib/api-node 中存在
更新配置文件:

{
  "tools": [
    {
      "name": "your_new_tool",
      "description": "新工具的描述",
      "controller": "YourNewController",
      "method": "yourMethodUsingGET"
    }
  ]
}

测试新工具:

yuce-mcp-api-bridge serve --config updated-config.json --verbose

🔍 故障排除

常见问题及解决方案

1. Controller 未找到

错误信息:

Controller UserController not found, skipping tool user_get_info

解决方案:

检查 Controller 名称拼写是否正确
确认 @ylib/api-node 包已正确安装和构建
运行 yuce-mcp-api-bridge list-controllers 查看可用列表
检查 Controller 是否正确从 @ylib/api-node/controller 导出

2. 方法不存在

错误信息:

Method getUserInfoUsingGET not found in UserController

解决方案:

检查方法名拼写是否正确
确认 Controller 中确实包含该方法
查看 Controller 源码确认方法签名
检查 API 包版本是否最新

3. 网络连接问题

错误信息:

API request failed: connect ECONNREFUSED

解决方案:

检查 API 基础 URL 是否正确
确认网络连接正常
验证访问令牌是否有效
检查防火墙设置

4. 权限错误

错误信息:

API request failed: 401 Unauthorized

解决方案:

检查访问令牌是否正确
确认令牌是否过期
验证用户权限是否足够
检查 API 服务状态

5. 配置文件格式错误

错误信息:

Invalid configuration file format

解决方案:

验证 JSON 格式是否正确
检查必需字段是否完整
使用 yuce-mcp-api-bridge init 生成标准配置
对比示例配置文件

诊断命令

# 检查环境
node --version
pnpm --version

# 验证构建
pnpm --filter yuce-mcp-api-bridge build

# 检查命令可用性
yuce-mcp-api-bridge --version

# 生成诊断配置
yuce-mcp-api-bridge init --output diagnostic-config.json
yuce-mcp-api-bridge status --config diagnostic-config.json

# 测试基础功能
yuce-mcp-api-bridge list-controllers

# 详细模式调试
yuce-mcp-api-bridge serve --controllers UserController --verbose

日志分析

使用 --verbose 选项可以获得详细的运行日志：

yuce-mcp-api-bridge serve --controllers UserController --verbose

日志会显示：

Controller 加载过程
工具注册状态
API 请求详情
错误堆栈信息

📈 性能优化

选择性暴露 API

只暴露必要的 Controller 和方法以提高性能：

{
  "tools": [
    {
      "name": "essential_user_info",
      "description": "获取必要的用户信息",
      "controller": "UserController",
      "method": "getUserInfoUsingGET",
      "enabled": true
    }
    // 禁用不需要的工具
  ]
}

超时设置

合理设置 API 超时时间：

{
  "api": {
    "timeout": 15000 // 15秒，根据网络环境调整
  }
}

缓存策略

对于读取频繁的数据，考虑在应用层实现缓存机制。

🔒 安全考虑

访问控制

使用有限权限的访问令牌
定期轮换访问令牌
只暴露必要的 API 方法

网络安全

使用 HTTPS 连接
配置适当的防火墙规则
监控异常 API 调用

配置安全

将敏感信息 (如访问令牌) 存储在环境变量中
不要将配置文件提交到版本控制系统
使用配置文件模板而非实际配置

安全配置示例:

{
  "api": {
    "baseURL": "${API_BASE_URL}",
    "accessToken": "${ACCESS_TOKEN}",
    "timeout": 30000
  }
}

对应的环境变量：

export API_BASE_URL="https://api.example.com"
export ACCESS_TOKEN="your-secret-token"

📚 完整文档

本 README 提供了基本的使用说明，更详细的文档请参考：

📖 文档中心 - 完整的文档导航
🚀 完整使用指南 - 详细的功能介绍和配置说明
📖 API 参考 - 完整的 CLI 和配置 API 文档
📋 可用 Controllers - 所有可用的 API Controllers 详细说明
🏗️ 架构设计 - 系统架构和设计原理
💡 使用示例 - 各种场景的使用示例
🚀 部署指南 - 生产环境部署指南

📚 更多资源

🤝 社区支持

GitHub Issues: 提交 Bug 报告和功能请求
技术文档: 查看项目 Wiki
开发指南: 参与项目贡献

📄 许可证

MIT License - 详见 LICENSE 文件

如有任何问题或建议，欢迎提交 Issue 或 Pull Request！

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

MCP API Bridge 完整使用指南

🎯 概述

核心价值

🏗️ 架构设计

🚀 快速开始

环境要求

1. 安装和构建

2. 第一次运行

3. 验证安装

🎛️ 命令行工具详解

serve - 启动 MCP 服务器

init - 生成配置文件

list-controllers - 列出可用 Controllers

status - 检查配置状态

⚙️ 配置管理

配置文件结构

完整配置示例

预设配置模板

数据分析师配置

系统管理员配置

🔌 集成指南

与 Claude Desktop 集成

与其他 MCP 客户端集成

📋 支持的 Controllers

核心业务 Controllers

数据分析 Controllers

ETL 和数据处理 Controllers

系统集成 Controllers

🛠️ 开发指南

项目结构

本地开发

调试技巧

添加新 Controller 支持

🔍 故障排除

常见问题及解决方案

1. Controller 未找到

2. 方法不存在

3. 网络连接问题

4. 权限错误

5. 配置文件格式错误

诊断命令

日志分析

📈 性能优化

选择性暴露 API

超时设置

缓存策略

🔒 安全考虑

访问控制

网络安全

配置安全

📚 完整文档

📚 更多资源

🤝 社区支持

📄 许可证

`serve` - 启动 MCP 服务器

`init` - 生成配置文件

`list-controllers` - 列出可用 Controllers

`status` - 检查配置状态