🚀 LeanIX MCP 集成

本项目是一个将 LeanIX 连接至 AI 助手的模型上下文协议 (MCP) 服务器。它能把 LeanIX 的 GraphQL API 暴露为 MCP 工具，供 AI 助手调用，为 LeanIX 与 AI 助手的交互搭建了桥梁。

🚀 快速开始

先决条件

• Node.js (v14 或更高版本)
• 一个 LeanIX 工作区和 API 令牌
• 对 GraphQL 和 MCP 的基本理解

操作步骤

1. 克隆此仓库。
2. 安装依赖项：

   npm install
   

3. 在根目录下创建一个 .env 文件，其中包含您的 LeanIX 凭据：

   LEANIX_SUBDOMAIN=your-workspace-subdomain
   LEANIX_TOKEN=your-api-token
   

✨ 主要特性

此集成提供了五个用于 LeanIX 操作的 MCP 工具：

1. 事实表概览：获取工作区中事实表的数量和统计信息。
2. 搜索：通过名称查找事实表。
3. 订阅管理：查看特定事实表的订阅者。
4. 创建事实表：向工作区添加新的事实表。
5. 更新事实表：修改现有事实表的信息。

📚 详细文档

项目结构

├── server.js            # 主 MCP 服务器设置和初始化
├── leanix-client.js     # LeanIX API 客户端实现
├── api                  # LeanIX API 定义和端点
├── mutation            # GraphQL 变体定义
├── datamodel           # 数据模型和类型定义
├── .env                # 环境配置
└── src/
    ├── config/
    │   └── config.js         # 加载并验证环境变量中的 LeanIX 凭据
    ├── graphql/
    │   └── queries/         # GraphQL 查询和变体
    │       ├── factSheetQueries.js     # 事实表操作的查询
    │       └── workspaceQueries.js     # 工作区级别操作的查询
    ├── tools/
    │   └── workspaceTools.js # 定义并注册五个 MCP 工具
    ├── types/
    │   └── schemas.js       # Zod 模式用于工具参数的验证
    └── utils/
        └── responseHandler.js # 以 MCP 兼容结构格式化响应

常见问题及解决方案

1. GraphQL 架构不匹配：始终检查当前 LeanIX API 架构。架构可能会随时间变化。
2. 响应格式：所有 MCP 工具响应必须遵循以下格式：

   {
     content: [{
       type: "text",
       text: "your response here"
     }]
   }
   

3. 错误处理：始终使用 withErrorHandling 包装工具实现，以确保正确的错误响应。
4. 环境变量：在进行任何 API 调用之前，确保正确加载和验证环境变量。

Claude Desktop 配置

要将此 MCP 服务器与 Claude Desktop 使用，请将服务器配置添加到 Claude 的配置文件中。配置文件通常位于：

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

添加以下配置：

{
    "mcpServers": {
      "myserver": {
        "command": "node",
        "args": [
          "/path/to/your/lean/server.js"
        ]
      }
    }
}

将 /path/to/your/lean/server.js 替换为 server.js 文件的绝对路径。这会指示 Claude Desktop：

1. 在需要时启动此 MCP 服务器。
2. 通过它进行 LeanIX 操作。
3. 使用 Node.js 运行它。

测试您的集成

1. 启动服务器：

   node server.js
   

2. 打开浏览器并访问 http://localhost:3000

调试技巧

• 确保所有环境变量都已正确设置。
• 检查控制台输出以获取任何错误或警告信息。
• 使用浏览器开发者工具检查网络请求和响应。

📦 资源

• LeanIX 文档
• GraphQL 官方网站
• MCP 协议文档