AgileConfig MCP Server

基于 AgileConfig 的 MCP (Model Context Protocol) 服务器。将 AgileConfig 配置中心的 全部 RESTful API 暴露为 MCP 工具，让你在 AI 工具中直接用自然语言管理配置中心。

目录

• 功能概览
• 在 AI 工具中使用
  • Claude Code
  • Claude Desktop
  • VS Code / Cursor
  • Windsurf
  • Gemini CLI
  • Codex CLI
  • AI 工具配置速查表
• 本地使用
  • 环境准备
  • 克隆 & 安装
  • 配置环境变量
  • 编译 & 运行
  • 使用 MCP Inspector 调试
  • 在 AI 工具中连接本地 MCP
• 全部 MCP 工具列表
• 权限体系
• 使用示例
• 环境变量参考
• 项目结构
• 发布到 npm
• 参考链接

功能概览

本 MCP 服务器完整覆盖了 AgileConfig 的 9 大功能模块、36 个 MCP 工具，对应 AgileConfig 的全部 RESTful API：

| 模块 | 工具数 | 涵盖能力 | |------|--------|----------| | 📱 应用管理 | 5 | 创建、查看、编辑、删除应用 | | ⚙️ 配置管理 | 11 | 配置增删改查、发布/下线、历史查看、版本回滚 | | 🖥️ 节点管理 | 3 | 集群节点查看、添加、移除 | | 👤 用户管理 | 7 | 用户 CRUD、登录、密码修改 | | 🔐 权限管理 | 2 | 查看和设置用户的细粒度 RBAC 权限 | | 📋 系统日志 | 1 | 按应用/类型/时间范围查询操作日志 | | 🔌 客户端管理 | 2 | 查看已连接客户端、强制断开 | | 🔍 服务发现 | 3 | 服务注册、查询、注销 | | ⚙️ 系统设置 | 2 | 查看和更新系统级配置 |

核心特性

• 🚀 完整 API 覆盖 — 实现了 AgileConfig 所有 RESTful API，无遗漏
• 🌍 多环境支持 — 按 env 参数隔离 DEV/PROD 等环境；不设 env 时操作所有环境
• 🔐 双认证模式 — Admin Basic Auth（管理操作）和 App Secret Basic Auth（客户端拉取配置）
• ⚡ 配置实时生效 — 发布后 AgileConfig 通过 WebSocket 实时推送至所有客户端
• 📦 npx 零安装 — 发布到 npm 后，一行配置即可使用，无需克隆和编译
• 🛡️ 错误处理完善 — 所有 API 调用均包含超时控制、异常捕获和结构化错误返回

在 AI 工具中使用

前提条件：Node.js >= 18，且有一个运行中的 AgileConfig 服务端。

Claude Code

编辑 ~/.claude/settings.json（全局）或项目根目录的 .claude/settings.json（项目级）：

{
  "mcpServers": {
    "agileconfig": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "agileconfig-mcp-server"],
      "env": {
        "AGILECONFIG_URL": "http://your-agileconfig-server:5000",
        "AGILECONFIG_ADMIN_USERNAME": "admin",
        "AGILECONFIG_ADMIN_PASSWORD": "your-password",
        "AGILECONFIG_ENV": "DEV"
      }
    }
  }
}

重启 Claude Code 后，用自然语言操作配置中心：

"帮我看下 AgileConfig 上有哪些应用" "给 my-app 添加一个数据库连接字符串配置" "查看 my-app 的配置发布历史" "创建用户 tester，角色 NormalUser" "检查所有服务节点的在线状态" "把 my-app 的配置回滚到上一个版本"

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "agileconfig": {
      "command": "npx",
      "args": ["-y", "agileconfig-mcp-server"],
      "env": {
        "AGILECONFIG_URL": "http://your-agileconfig-server:5000",
        "AGILECONFIG_ADMIN_USERNAME": "admin",
        "AGILECONFIG_ADMIN_PASSWORD": "your-password",
        "AGILECONFIG_ENV": "DEV"
      }
    }
  }
}

VS Code / Cursor

在 VS Code 的 mcp.json 或 Cursor 的 .cursor/mcp.json 中配置：

{
  "mcpServers": {
    "agileconfig": {
      "command": "npx",
      "args": ["-y", "agileconfig-mcp-server"],
      "env": {
        "AGILECONFIG_URL": "http://your-agileconfig-server:5000",
        "AGILECONFIG_ADMIN_USERNAME": "admin",
        "AGILECONFIG_ADMIN_PASSWORD": "your-password",
        "AGILECONFIG_ENV": "DEV"
      }
    }
  }
}

Windsurf

编辑 ~/.codeium/windsurf/mcp.json：

{
  "mcpServers": {
    "agileconfig": {
      "command": "npx",
      "args": ["-y", "agileconfig-mcp-server"],
      "env": {
        "AGILECONFIG_URL": "http://your-agileconfig-server:5000",
        "AGILECONFIG_ADMIN_USERNAME": "admin",
        "AGILECONFIG_ADMIN_PASSWORD": "your-password"
      }
    }
  }
}

Gemini CLI

gemini mcp add agileconfig -- npx -y agileconfig-mcp-server

执行后 Gemini CLI 会使用当前 shell 的环境变量，请确保已设置：

export AGILECONFIG_URL=http://your-agileconfig-server:5000
export AGILECONFIG_ADMIN_USERNAME=admin
export AGILECONFIG_ADMIN_PASSWORD=your-password

Codex CLI

codex mcp add agileconfig -- npx -y agileconfig-mcp-server

AI 工具配置速查表

| AI 工具 | 配置文件位置 | 配置方式 | |---------|-------------|----------| | Claude Code | ~/.claude/settings.json | JSON 配置 | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | JSON 配置 | | VS Code | .vscode/mcp.json | JSON 配置 | | Cursor | .cursor/mcp.json | JSON 配置 | | Windsurf | ~/.codeium/windsurf/mcp.json | JSON 配置 | | Gemini CLI | — | gemini mcp add 命令 | | Codex CLI | — | codex mcp add 命令 |

本地使用

如果你不想等待 npm 发布，或者需要二次开发，可以在本地克隆并使用。

环境准备

• Node.js: >= 18（推荐 20+）
• npm: >= 9
• AgileConfig 服务端: 需要有一个运行中的 AgileConfig 实例

克隆 & 安装

# 进入你的工作目录
cd /path/to/your/workspace

# 克隆项目
git clone <repo-url> agile-confg-mcp
cd agile-confg-mcp

# 安装依赖
npm install

配置环境变量

# 从模板创建 .env
cp .env.example .env

编辑 .env 文件，填入你的 AgileConfig 服务端信息：

# AgileConfig 服务端地址
AGILECONFIG_URL=http://localhost:5000

# Admin 认证（用户名固定为 admin）
AGILECONFIG_ADMIN_USERNAME=admin
AGILECONFIG_ADMIN_PASSWORD=123456

# 请求超时（毫秒）
AGILECONFIG_TIMEOUT=30000

# 默认环境。留空或设为 "" 将操作所有环境
AGILECONFIG_ENV=DEV

编译 & 运行

# 编译 TypeScript → dist/
npm run build

# 直接启动服务器
npm start

启动后 MCP 服务器会通过 stdio（标准输入输出）与 AI 工具通信，日志输出到 stderr：

[AgileConfig MCP Server] 已启动
[AgileConfig MCP Server] 目标地址: http://localhost:5000
[AgileConfig MCP Server] 默认环境: DEV

使用 MCP Inspector 调试

MCP 官方提供了 Inspector 工具，可以直观地查看工具列表、测试工具调用、检查协议消息：

# 启动 Inspector（会自动打开浏览器）
npm run inspector

浏览器打开后：

1. 左侧 Tools 面板 — 查看所有注册的 36 个工具及其参数 schema
2. 点击工具名 — 在右侧填入参数，点击 "Run" 测试调用
3. 底部 Console — 查看 JSON-RPC 请求和响应的原始报文

如果只想验证服务器能否正常启动（不打开浏览器）：

# 直接经 stdio 启动，发送一个 list_tools 请求验证
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

在 AI 工具中连接本地 MCP

使用本地路径代替 npx，在 AI 工具的 MCP 配置中指定为 node + 本地 dist/index.js 路径：

{
  "mcpServers": {
    "agileconfig": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/agile-confg-mcp/dist/index.js"],
      "env": {
        "AGILECONFIG_URL": "http://your-agileconfig-server:5000",
        "AGILECONFIG_ADMIN_USERNAME": "admin",
        "AGILECONFIG_ADMIN_PASSWORD": "your-password",
        "AGILECONFIG_ENV": "DEV"
      }
    }
  }
}

对比：npx 方式适合最终用户，无需克隆代码；本地 node 方式适合开发调试，修改代码后 npm run build 即可生效。

全部 MCP 工具列表

应用管理

| 工具名 | 说明 | API | |--------|------|-----| | agileconfig_list_apps | 获取所有应用列表 | GET /api/app | | agileconfig_get_app | 根据 ID 获取单个应用详情 | GET /api/app/{id} | | agileconfig_create_app | 创建新应用（名称/分组/密钥/继承等） | POST /api/app | | agileconfig_update_app | 编辑应用信息 | PUT /api/app/{id} | | agileconfig_delete_app | 删除应用（不可逆） | DELETE /api/app/{id} |

配置管理

| 工具名 | 说明 | 认证 | API | |--------|------|------|-----| | agileconfig_get_published_configs | 获取已发布配置（供客户端拉取） | App Secret | GET /api/config/app/{appId} | | agileconfig_get_all_configs | 获取所有配置（含编辑中未发布项） | Admin | GET /api/config | | agileconfig_get_config | 获取单个配置项详情 | Admin | GET /api/config/{id} | | agileconfig_create_config | 添加新配置项（键值对） | Admin | POST /api/config | | agileconfig_update_config | 修改配置项的值/分组/描述 | Admin | PUT /api/config/{id} | | agileconfig_delete_config | 删除配置项（软删除） | Admin | DELETE /api/config/{id} | | agileconfig_publish_config | 发布应用的全部待处理变更 | Admin | POST /api/app/publish | | agileconfig_publish_single_config | 上线单个配置项 | Admin | POST /api/config/publish/{id} | | agileconfig_offline_config | 下线单个配置项 | Admin | POST /api/config/offline/{id} | | agileconfig_get_publish_history | 查看应用的发布历史记录 | Admin | GET /api/app/Publish_History | | agileconfig_rollback_config | 回滚到指定历史版本 | Admin | POST /api/app/rollback |

节点管理

| 工具名 | 说明 | API | |--------|------|-----| | agileconfig_list_nodes | 获取集群所有节点（含在线状态/心跳时间） | GET /api/node | | agileconfig_add_node | 添加节点到集群 | POST /api/node | | agileconfig_delete_node | 从集群移除节点 | DELETE /api/node |

用户管理

| 工具名 | 说明 | API | |--------|------|-----| | agileconfig_list_users | 获取所有用户列表 | GET /api/user | | agileconfig_get_user | 获取单个用户详情 | GET /api/user/{id} | | agileconfig_create_user | 创建用户（用户名/密码/角色/团队） | POST /api/user | | agileconfig_update_user | 编辑用户（含冻结/解冻） | PUT /api/user/{id} | | agileconfig_delete_user | 删除用户 | DELETE /api/user/{id} | | agileconfig_change_password | 修改指定用户的密码 | PUT /api/user/{id}/password | | agileconfig_user_login | 用户登录，返回 JWT Token | POST /api/user/login |

权限管理

| 工具名 | 说明 | API | |--------|------|-----| | agileconfig_get_user_permissions | 查看用户的所有权限 | GET /api/user/{id}/permissions | | agileconfig_set_user_permissions | 设置用户的 RBAC 权限 | PUT /api/user/{id}/permissions |

系统日志

| 工具名 | 说明 | API | |--------|------|-----| | agileconfig_get_syslogs | 按应用/类型/时间范围查询操作日志 | GET /api/syslog |

客户端管理

| 工具名 | 说明 | API | |--------|------|-----| | agileconfig_list_clients | 查看已连接客户端（地址/心跳/标签） | GET /api/client | | agileconfig_disconnect_client | 强制断开指定客户端 | POST /api/client/disconnect |

服务发现

| 工具名 | 说明 | API | |--------|------|-----| | agileconfig_list_services | 查看所有已注册服务及健康状态 | GET /api/service | | agileconfig_register_service | 注册服务（含元数据） | POST /api/service | | agileconfig_unregister_service | 注销服务 | DELETE /api/service |

系统设置

| 工具名 | 说明 | API | |--------|------|-----| | agileconfig_get_settings | 查看系统设置（CORS/JWT 等） | GET /api/setting | | agileconfig_update_settings | 更新系统设置 | PUT /api/setting |

权限体系

AgileConfig 使用 RBAC（基于角色的访问控制），权限分为全局范围和应用范围：

| 权限 Key | 说明 | |----------|------| | APP_ADD | 添加应用 | | APP_EDIT | 编辑应用 | | APP_DELETE | 删除应用 | | APP_AUTH | 应用授权管理 | | CONFIG_ADD | 添加配置项 | | CONFIG_EDIT | 编辑配置项 | | CONFIG_DELETE | 删除配置项 | | CONFIG_PUBLISH | 发布配置 | | CONFIG_OFFLINE | 下线配置 | | NODE_ADD | 添加节点 | | NODE_DELETE | 移除节点 | | CLIENT_DISCONNECT | 断开客户端连接 | | USER_ADD | 创建用户 | | USER_EDIT | 编辑用户 | | USER_DELETE | 删除用户 |

权限范围：

• GLOBAL — 全局权限，对所有资源生效
• APP_{appId} — 仅对指定应用生效（例如 APP_my-app）

使用示例

示例 1：配置管理全流程

用户: 帮我在 AgileConfig 中为 my-app 添加数据库连接配置

AI 执行流程:
──查看现有配置
  → agileconfig_get_all_configs(appId="my-app")
──添加配置项
  → agileconfig_create_config(
      appId="my-app",
      key="ConnectionStrings:Default",
      value="Server=prod-db;Database=main;User=sa",
      description="生产数据库连接字符串",
      env="DEV"
    )
──发布到客户端
  → agileconfig_publish_config(appId="my-app", env="DEV")

示例 2：运维排障

用户: 检查 AgileConfig 集群运行状态，看看有没有异常

AI 执行流程:
──检查节点健康
  → agileconfig_list_nodes()
──查看已连接客户端
  → agileconfig_list_clients()
──查看错误日志
  → agileconfig_get_syslogs(logType="Error", pageSize=20)
──汇总结果，告知用户节点/客户端/异常情况

示例 3：新成员入职 — 创建账号并授权

用户: 新同事 zhangsan 入职了，给他创建 AgileConfig 账号，让他管理 my-app 的配置

AI 执行流程:
──创建用户
  → agileconfig_create_user(
      userName="zhangsan",
      password="temp@123456",
      role="NormalUser"
    )
──分配权限（仅限 my-app 的配置管理权限）
  → agileconfig_set_user_permissions(
      userId="<返回的用户ID>",
      permissions='[
        {"functionKey":"CONFIG_ADD","appId":"my-app","enable":true},
        {"functionKey":"CONFIG_EDIT","appId":"my-app","enable":true},
        {"functionKey":"CONFIG_PUBLISH","appId":"my-app","enable":true}
      ]'
    )

示例 4：跨环境操作

用户: 把 DEV 环境的 my-app 配置复制到 PROD

AI 执行流程:
──读取 DEV 配置
  → agileconfig_get_published_configs(appId="my-app", appSecret="xxx", env="DEV")
──逐条在 PROD 创建
  → agileconfig_create_config(appId="my-app", key="...", value="...", env="PROD")
──发布 PROD 配置
  → agileconfig_publish_config(appId="my-app", env="PROD")

环境变量参考

| 变量名 | 必填 | 说明 | 默认值 | |--------|------|------|--------| | AGILECONFIG_URL | 是 | AgileConfig 服务端地址 | http://localhost:5000 | | AGILECONFIG_ADMIN_USERNAME | 否 | Admin 用户名 | admin | | AGILECONFIG_ADMIN_PASSWORD | 否 | Admin 密码 | 123456 | | AGILECONFIG_TIMEOUT | 否 | API 请求超时（毫秒） | 30000 | | AGILECONFIG_ENV | 否 | 默认操作环境，留空 = 操作所有环境 | DEV |

项目结构

agile-confg-mcp/
├── src/
│   ├── index.ts                  # MCP 服务器主入口（工具注册 + 调用分发，~1100 行）
│   ├── agileconfig-client.ts     # AgileConfig REST API 客户端（~450 行）
│   └── types.ts                  # 完整的 TypeScript 类型定义（~250 行）
├── dist/                         # 编译产物（发布到 npm）
├── package.json                  # 含 bin 入口，支持 npx
├── tsconfig.json
├── .env.example                  # 环境变量模板
├── .gitignore
└── README.md

发布到 npm

# 确保已登录 npm
npm login

# 发布（prepublishOnly 脚本会自动执行 npm run build 确保 dist/ 最新）
npm publish

发布后，任何人都可以通过 npx 零安装使用：

npx -y agileconfig-mcp-server

参考链接

• AgileConfig 开源项目 — 基于 .NET Core 的轻量级分布式配置中心
• AgileConfig RESTful API 介绍 — API 完整文档
• MCP 协议规范 — Model Context Protocol 官方文档
• MCP TypeScript SDK — TypeScript SDK 参考

MIT License

🤖 Generated with Claude Code