Aspro.cloud Unofficial Mcp

aspro-mcp

一个模型上下文协议服务，可将 Aspro.Cloud REST API 提供给大模型客户端（Claude Desktop、Claude Code 等）。服务内置 OpenAPI 规范，因此模型可以自行发现模块、实体和方法，并安全地调用它们。

功能

• 自描述。 模型通过 aspro_search / aspro_list_* → aspro_describe 浏览 API，然后再进行调用，无需记忆端点。
• 关键词搜索支持俄语词形变化处理，因此 сделка、сделки 和 создать задачу 都能匹配到正确的端点。
• 读取和写入是独立的工具。 aspro_call 仅支持读取，并标注为只读；aspro_write 标注为具有破坏性，因此客户端可以自动批准读取操作，而不会连删除操作也一并放行。
• 通过 ASPRO_READ_ONLY=1 启用只读模式——任何修改操作都会在请求离开进程之前被拒绝。
• API 密钥不会传递给模型。 工具返回的所有 URL 和错误消息中都会对其进行脱敏。
• 响应架构。 aspro_describe 会报告端点返回的字段，而不只是它接受的字段。
• 默认使用 Form-urlencoded POST（Aspro 预期的内容类型），并支持数组和嵌套对象。
• 通过 ASPRO_COMPANY（子域名）或完整的 ASPRO_BASE_URL 配置租户。

安装

直接通过 npm 运行，无需检出代码：

npx -y aspro-mcp

发布的包是单个捆绑文件，没有运行时依赖，因此 npx 只需获取一个包，即使缓存为空，也能在几秒内启动服务。

或者克隆并构建：

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

需要 Node.js ≥ 18。

连接到客户端

Claude Desktop / Claude Code

在 env 代码块中传入凭据——这是推荐的配置方式，也是唯一适用于 npx 的方式：

{
  "mcpServers": {
    "aspro": {
      "command": "npx",
      "args": ["-y", "aspro-mcp"],
      "env": {
        "ASPRO_COMPANY": "your_company",
        "ASPRO_API_KEY": "your_api_key_here"
      }
    }
  }
}

对于本地检出代码，请改为指向构建后的入口点：

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

其他 MCP 客户端

任何支持通过 stdio 使用 MCP 的客户端都可以运行 npx -y aspro-mcp（或 node dist/index.js）。

启动时出现“Connection timed out”

0.2.1 及更早版本会拉取约 100 个传递依赖，npx 可能需要 30 秒或更长时间来安装——超过了 MCP 客户端的等待时间（Claude Code 会在 30 秒后放弃），因此运行正常的服务也会显示为失败。0.2.2 及更高版本以单个捆绑文件发布，可在几秒内启动。

如果客户端仍启动旧的缓存副本，请通过 "args": ["-y", "aspro-mcp@latest"] 明确指定当前版本。若要彻底绕开 npx，请先安装一次该包，然后直接运行二进制文件：

npm install -g aspro-mcp

{
  "mcpServers": {
    "aspro": {
      "command": "aspro-mcp",
      "env": {
        "ASPRO_COMPANY": "your_company",
        "ASPRO_API_KEY": "your_api_key_here"
      }
    }
  }
}

配置

配置来自环境变量。本地检出代码也可以在包根目录中使用 .env 文件，无论客户端的工作目录是什么，都会读取该文件：

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_READ_ONLY=1               # optional; refuse create/update/delete entirely
# ASPRO_MAX_RESPONSE_CHARS=60000  # optional; cap on a single tool result

使用 npx 时，包位于 npm 缓存中，因此没有可读取的 .env 文件——请使用上方所示的 env 代码块。环境中已有的变量始终优先于 .env 中的变量。

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

即使没有凭据，服务仍会启动并提供发现工具；这些工具完全依靠内置规范离线运行，只有调用工具会报告配置错误。

暴露的工具

工具	功能
aspro_list_modules	列出顶层模块（crm、fin、task 等）及其实体数 / 操作数。
aspro_list_entities	列出模块中的实体，以及每个实体可用的方法。
aspro_list_methods	列出模块的操作（HTTP 方法 + 路径 + 简短说明），可按实体筛选。
aspro_search	在模块 / 实体 / 方法 / 路径 / 说明 / 标签中进行关键词搜索。
aspro_describe	获取某项操作的完整架构：参数、请求体字段、响应字段，以及是否会修改数据。
aspro_call	执行读取（list / get）。返回 { status, ok, url, data }。
aspro_write	执行创建 / 更新 / 删除操作。设置 ASPRO_READ_ONLY 后不会注册此工具。

推荐流程：search/list_* → describe → call/write。

安全说明

• Aspro 通过 HTTP GET 提供 /delete/{id}。 HTTP 方法无法说明操作是否具有破坏性，因此不要据此制定审批规则。此服务根据操作的方法段对操作分类，并将其报告为 mutating；aspro_write 带有破坏性操作标注，而 aspro_call 会拒绝任何会修改数据的操作。
• API 密钥从环境变量读取，并作为 ?api_key=... 附加到每个请求中。返回给模型的 URL 和错误消息会对其进行隐藏，但密钥仍保存在客户端配置中——切勿提交 .env。
• 此服务没有按端点设置的允许列表：配置完成后，aspro_write 可以访问规范中的任何修改类端点。请使用权限范围最小的专用 API 密钥；如果模型不应执行写入操作，请设置 ASPRO_READ_ONLY=1。
• 将工具输出视为不可信内容：Aspro 实体（自定义字段值、说明等）可能包含用户提供的内容。

关于捆绑规范的说明

该规范完全没有记录查询参数，但 list 端点接受多个查询参数。这些参数已在实际租户中验证，并在服务说明中告知模型：

参数	行为
page=N	从 1 开始的页码。
limit=N	缩小页面范围。无论设置的值有多高，每页最多返回 25 项。
filter[<field>]=v	按响应字段精确匹配，例如 filter[id]=193。并非所有字段都支持筛选。
search=<text>	在实体中进行全文搜索。

需要注意的两个陷阱：

• 未知或不受支持的查询参数会被静默忽略，而不是被拒绝。未生效的筛选条件看起来与匹配所有内容的筛选条件完全相同，因此请核对返回的项目。
• total 报告的是未筛选的数量，因此无法告知你有多少行匹配筛选条件。

未发现可用的排序参数。

规范中没有记录按账户配置的自定义字段（cf_<id> / cf_<alias>），因为这些字段因租户而异。它们仍会包含在响应中，也可以在 body 中发送。

开发

npm run dev      # rebuild the bundle on change
npm run build    # tsc (type-check) + esbuild bundle
npm test         # smoke + e2e

npm run build 会使用 tsc 进行类型检查，然后使用 esbuild 将服务及其依赖打包到 dist/index.js 中（参见 build.mjs）。因此，MCP SDK、zod 和 dotenv 都是 devDependencies：它们会被编译进包中，用户无需安装。它们的许可证文本会收集到 dist/THIRD_PARTY_LICENSES.txt 中。

这两个测试套件都不会访问网络。npm run smoke 会对 fetch 进行存根替换，并断言打包后的规范可以解析、变更操作分类正确（包括通过 GET 提供的删除操作）、搜索能找到预期的端点、URL 构建正确、API 密钥绝不会出现在工具结果或错误中，以及超大响应会被截断。npm run e2e 会通过 stdio 启动打包后的服务，并使用真实的 MCP 客户端检查公开的工具及其注释，还会验证 ASPRO_READ_ONLY 确实会屏蔽 aspro_write。

项目结构

src/
  index.ts    MCP server (tool registration + entry point)
  config.ts   environment loading and validation
  client.ts   HTTP client (URL building, redaction, form-urlencoded POSTs, timeouts, size caps)
  spec.ts     OpenAPI indexer (modules / entities / methods / search / describe)
  smoke.ts    offline unit tests
  e2e.ts      stdio round-trip against a real MCP client
spec/
  openapi.json  bundled Aspro.Cloud OpenAPI spec
build.mjs     esbuild bundling + third-party license collection

贡献

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

许可证

MIT — 请参阅 LICENSE。

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