# AgileConfig MCP Server

[![npm version](https://img.shields.io/npm/v/agileconfig-mcp-server)](https://www.npmjs.com/package/agileconfig-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)

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

---

## 目录

- [功能概览](#功能概览)
- [在 AI 工具中使用](#在-ai-工具中使用)
  - [Claude Code](#claude-code)
  - [Claude Desktop](#claude-desktop)
  - [VS Code / Cursor](#vs-code--cursor)
  - [Windsurf](#windsurf)
  - [Gemini CLI](#gemini-cli)
  - [Codex CLI](#codex-cli)
  - [AI 工具配置速查表](#ai-工具配置速查表)
- [本地使用](#本地使用)
  - [环境准备](#环境准备)
  - [克隆 & 安装](#克隆--安装)
  - [配置环境变量](#配置环境变量)
  - [编译 & 运行](#编译--运行)
  - [使用 MCP Inspector 调试](#使用-mcp-inspector-调试)
  - [在 AI 工具中连接本地 MCP](#在-ai-工具中连接本地-mcp)
- [全部 MCP 工具列表](#全部-mcp-工具列表)
- [权限体系](#权限体系)
- [使用示例](#使用示例)
- [环境变量参考](#环境变量参考)
- [项目结构](#项目结构)
- [发布到 npm](#发布到-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`（项目级）：

```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）：

```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"
      }
    }
  }
}
```

### VS Code / Cursor

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

```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`：

```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

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

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

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

### Codex CLI

```bash
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](https://github.com/dotnetcore/AgileConfig) 实例

### 克隆 & 安装

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

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

# 安装依赖
npm install
```

### 配置环境变量

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

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

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

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

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

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

### 编译 & 运行

```bash
# 编译 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 工具，可以直观地查看工具列表、测试工具调用、检查协议消息：

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

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

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

```bash
# 直接经 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` 路径：

```json
{
  "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

```bash
# 确保已登录 npm
npm login

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

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

```
npx -y agileconfig-mcp-server
```

---

## 参考链接

- [AgileConfig 开源项目](https://github.com/dotnetcore/AgileConfig) — 基于 .NET Core 的轻量级分布式配置中心
- [AgileConfig RESTful API 介绍](https://cloud.tencent.cn/developer/article/1776592) — API 完整文档
- [MCP 协议规范](https://modelcontextprotocol.io) — Model Context Protocol 官方文档
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) — TypeScript SDK 参考

---

MIT License

---

🤖 Generated with [Claude Code](https://claude.com/claude-code)