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