aspro-mcp

一个 Model Context Protocol 服务器，将 Aspro.Cloud REST API 暴露给 LLM 客户端（Claude Desktop、Claude Code 等）。该服务器附带了打包好的 OpenAPI 规范，因此模型可以自行发现模块、实体和方法并安全地调用它们。

特性

• 自描述。 模型通过 aspro_list_modules → aspro_list_entities → aspro_list_methods → aspro_describe 浏览 API，然后才进行 aspro_call ——无需记忆端点。

• 子字符串搜索 涵盖模块 / 实体 / 方法 / 路径 / 描述 / 标签。

• 默认使用 form-urlencoded POST（Aspro 预期的内容类型），支持数组和嵌套对象处理。

• 路径参数替换，适用于 /get/{id}、/update/{id}、/delete/{id} 等。

• 租户配置，通过 ASPRO_COMPANY（子域名）或完整的 ASPRO_BASE_URL 进行配置。

安装

git clone https://github.com/bssth/aspro-mcp.git
cd aspro-mcp
npm install
npm run build

需要 Node.js ≥ 18。

配置

复制示例环境变量文件并填写：

cp .env.example .env

ASPRO_COMPANY=your_company        # the {company} part of https://{company}.aspro.cloud
ASPRO_API_KEY=your_api_key_here   # passed as ?api_key=... on every request
# ASPRO_BASE_URL=...              # optional; overrides the URL built from ASPRO_COMPANY
# ASPRO_TIMEOUT_MS=30000          # optional; default 30s

在您的 Aspro.Cloud 账户的 设置 → 集成 → API 中获取 API 密钥。

连接到客户端

Claude Desktop / Claude Code

将服务器添加到您的 MCP 配置中：

{
  "mcpServers": {
    "aspro": {
      "command": "node",
      "args": ["/absolute/path/to/aspro-mcp/dist/index.js"]
    }
  }
}

无论客户端在哪个工作目录下启动，服务器都会从项目根目录读取其 .env 文件。

其他 MCP 客户端

任何通过 stdio 使用 MCP 通信的客户端都可以运行 node dist/index.js（或 npm start）。

暴露的工具

推荐的流程是 search/list_* → describe → call。

开发

npm run dev      # tsc --watch
npm run build    # tsc
npm run smoke    # offline: exercises the spec indexer and URL builder

冒烟测试不涉及网络请求——它检查打包的 OpenAPI 规范是否可解析、操作是否可描述，以及 URL 构建器是否生成了格式正确的 URL。

项目布局

src/
  index.ts    MCP server (tool registration + entry point)
  config.ts   .env loading and validation
  client.ts   HTTP client (URL building, form-urlencoded POSTs, timeouts)
  spec.ts    OpenAPI indexer (modules / entities / methods / search / describe)
  smoke.ts    offline smoke test
spec/
  openapi.json  bundled Aspro.Cloud OpenAPI spec

安全说明

• API 密钥从环境变量中读取，并作为 ?api_key=... 附加到每个请求中。切勿提交 .env 文件。

• 服务器没有白名单——一旦配置，它就可以调用规范中描述的任何端点（包括像 /delete/{id} 这样的破坏性操作）。请使用具有最小必要权限的专用 API 密钥。

• 将工具输出视为不可信：Aspro 实体（自定义字段值、描述等）可能包含用户提供的内容。

贡献

欢迎提交 Issue 和 PR。提交前请运行 npm run build && npm run smoke。

许可证

MIT — 参见 LICENSE。

aspro-mcp 是一个非官方的第三方连接器，与 Aspro.Cloud 无关联。