# @znmin/apollo-mcp-server

只读的 Apollo 配置中心 MCP Server。**配置一次地址、应用和 Namespace，AI 调用时无需重复提供连接参数。**

- `npx` 直接启动，无需构建或安装 Python。
- 直连 Config Service，跳过服务发现，避免访问 Docker 内部 IP。
- 兼容 `CONFIG_URL`、`APP_ID`、`NAMESPACES` 环境变量。
- 支持多个 Namespace、按 key 查询、读取原始 YAML/JSON/XML/properties 内容。
- 只读取已发布配置，不提供编辑、删除或发布操作。

## 快速配置

需要 Node.js 20 或更新版本。在 MCP 客户端中添加：

```json
{
  "mcpServers": {
    "apollo": {
      "command": "npx",
      "args": ["-y", "@znmin/apollo-mcp-server@1.0.0"],
      "env": {
        "CONFIG_URL": "http://apollo-config.example.com:8080",
        "APP_ID": "my-app",
        "NAMESPACES": "application"
      }
    }
  }
}
```

将示例地址和应用替换为自己的配置，重新连接 MCP 后即可对 AI 说：

> 查看 Apollo 配置。
>
> 查一下 Apollo 中 redis.host 的值。

工具说明和服务初始化指令包含默认应用、集群和 Namespace，AI 无需再询问连接信息。
环境变量应放在 MCP 客户端的 `env` 配置中；直接运行 `npx` 时，使用当前终端的环境变量。

Windows 客户端若无法直接启动 `npx`，可使用 `command: "cmd"` 和
`args: ["/d", "/c", "npx", "-y", "@znmin/apollo-mcp-server@1.0.0"]`。

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `CONFIG_URL` | 是 | — | Config Service 的 HTTP(S) 地址，支持反向代理路径前缀；不是 Portal 管理后台 |
| `APP_ID` | 是 | — | 固定应用 ID |
| `NAMESPACES` | 否 | `application` | 允许查询的 Namespace，多个名称用英文逗号分隔 |
| `CLUSTER` | 否 | `default` | 固定集群 |
| `TIMEOUT_MS` | 否 | `10000` | 每个 HTTP 请求的超时时间，范围 1–300000 毫秒 |

兼容别名：

- `CONFIG_URL` → `APOLLO_CONFIG_URL` → `APOLLO_ADDRESS`
- `APP_ID` → `APOLLO_APP_ID`
- `NAMESPACES` → `APOLLO_NAMESPACES` → `APOLLO_NAMESPACE`
- `CLUSTER` → `APOLLO_CLUSTER`
- `TIMEOUT_MS` → `APOLLO_TIMEOUT_MS`

按上面的顺序选择第一个非空值。Namespace 会去空格、去重。未配置的 Namespace 会被拒绝查询。

不同环境应分别填写对应 Config Service 地址，并在客户端配置为不同的 MCP 实例。
此版本不支持 Portal 用户名密码、OpenAPI Token 或 Config Service AccessKey 签名；目标端点必须允许客户端读取配置。
不会自动跟随 HTTP 重定向，也不会调用 `/services/config`。

## MCP 工具

### `get_apollo_config`

无参数 `{}`：读取所有已配置 Namespace 的已发布配置。

```json
{}
```

只查询某个 key（在所有已配置 Namespace 中查找）：

```json
{ "key": "redis.host" }
```

只读取特定 Namespace（必须在 `NAMESPACES` 内）：

```json
{ "namespace": "datasource.yaml" }
```

返回单个匹配 Namespace 时，结果包含 `appId`、`cluster`、`namespace`、`releaseKey`、`configurations`；
返回多个时放在 `namespaces` 数组中。未找到 key、请求超时或上游出错时返回 MCP `isError: true`。
任意一个被查询的 Namespace 读取失败会使本次调用报错，不会静默返回不完整结果。

### `get_apollo_config_raw`

读取原始内容。`namespace` 可选；不传则读取全部已配置 Namespace。
YAML/JSON/XML Namespace 应包含文件后缀，例如 `datasource.yaml`。
优先使用 Apollo `/configfiles/raw/...` 接口；旧版 Apollo 没有此接口时，properties 回退到
`/configfiles/...`，其他受支持格式从 `/configs/...` 的 `content` 字段读取。可能受到 Apollo 服务端缓存影响。

### `list_apollo_namespaces`

无参数，列出本 MCP 实例预设的应用、集群和 Namespace；不扫描服务器。

## 开发和验证

```bash
npm ci --ignore-scripts
npm test
```

自动测试通过本地模拟 Config Service 验证配置解析、真实 MCP stdio 协议交互、无参查询、
多 Namespace、key 筛选、原始内容、错误、超时和直连行为，不需要真实凭证。

显式设置 `CONFIG_URL`、`APP_ID`、`NAMESPACES` 后执行：

```bash
npm run test:live
```

真实环境验证使用 MCP stdio 读取、按 key 查询和原始内容读取；控制台只打印统计信息，不打印配置值。
发布前运行：

```bash
npm test
npm pack --dry-run
npm publish --access public
```

所有连接信息由运行环境注入。示例地址、模拟测试数据均为占位值。
不要将真实配置值、密码、npm Token 或本机 `.npmrc` 提交到仓库。

## 参考

参见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。使用 MIT 许可证。