# AxonHub MCP Server

一个面向 AxonHub 管理数据的只读 MCP 服务器。AI 客户端可通过自然语言查询实例状态、项目、渠道、模型、请求和用量统计。

## 能力

- `axonhub_status`：总请求数、失败请求、延迟、Token 汇总、渠道成功率
- `axonhub_list_projects`：项目列表
- `axonhub_list_channels`：渠道状态、模型、限流和配额状态，不返回凭据
- `axonhub_list_models`：模型能力、价格、上下文限制和渠道关联数
- `axonhub_list_requests`：请求状态、延迟、执行、Token 和成本，不返回请求/响应正文
- `axonhub_usage`：按渠道、模型、API Key 或用户统计用量
- `axonhub_schema`：查看当前实例的 GraphQL 类型，兼容不同 AxonHub 版本
- `axonhub_graphql_query`：执行自定义只读 GraphQL 查询

所有 GraphQL 文档都会被解析并拒绝 `mutation` 和 `subscription`。返回数据会递归脱敏 API Key、密码、令牌、Cookie 和凭据字段。

## 安装

需要 Node.js 20 或更高版本。

```bash
npm install
npm run build
```

## 配置

管理端 GraphQL API 位于 `<AXONHUB_URL>/admin/graphql`，使用管理端登录令牌进行 Bearer 认证。不要把令牌写入仓库或 MCP 配置文件；建议通过启动环境注入。

已登录管理端时，可在该站点的浏览器开发者工具 Console 中执行下面的表达式取得当前会话令牌。令牌属于敏感凭据，不要粘贴到聊天、提交到 Git，或发送给他人；会话失效后需要重新获取。

```js
localStorage.getItem('axonhub_access_token')
```

```text
AXONHUB_URL=https://ai.neo7.cn
AXONHUB_TOKEN=<你的 AxonHub 管理端登录令牌>
AXONHUB_PROJECT_ID=<可选的默认项目 ID>
```

Codex/Claude Desktop 等支持 stdio MCP 的客户端可使用以下配置形式：

```json
{
  "mcpServers": {
    "axonhub": {
      "command": "node",
      "args": ["C:/absolute/path/to/axonhub-mcp/dist/index.js"],
      "env": {
        "AXONHUB_URL": "https://ai.neo7.cn",
        "AXONHUB_TOKEN": "${AXONHUB_TOKEN}",
        "AXONHUB_PROJECT_ID": "${AXONHUB_PROJECT_ID}"
      }
    }
  }
}
```

不同客户端对环境变量插值的支持不同。若客户端不支持 `${...}`，请从一个已设置这些环境变量的 shell 启动客户端，或使用操作系统的安全凭据注入机制。

## 开发与验证

```bash
npm test
npm run check
npm run build
```

本项目依据 AxonHub `unstable` 分支前端使用的 `/admin/graphql` 契约实现。常用工具固定选择安全字段；实例升级后如字段有变化，可先调用 `axonhub_schema` 检查实际 schema，再使用 `axonhub_graphql_query` 查询新增的只读数据。