upAPI

@upapi/mcp

upAPI（upapi.io）是一个 API 市场和网关。只需一个 API 密钥和一份共享配额，即可通过统一的 HTTP 协议调用目录中的所有操作——涵盖社交媒体、搜索、地图、金融、开发者工具、文件和浏览器操作——因此，集成第十个 API 的成本不会高于第一个。

**它不是什么：**它不是工作流或编排引擎，不是大模型提供商，也不是本地抓取库。每次调用都是在 api.upapi.io 上托管的一项操作；如何串联调用由你的代码或 Agent 决定。

规范 URL：https://upapi.io · 文档：https://upapi.io/docs · Agent 索引： https://upapi.io/llms.txt

将所有公开的 upAPI 操作作为 MCP 工具——包括网页搜索、SERP、社交资料、开发者工具查询、地理和金融数据——供 Agent 直接调用。

有两种连接方式，区别仅在于调用的身份验证方式：

	本地（stdio）	托管（HTTP）
端点	npx @upapi/mcp	https://app.upapi.io/api/mcp
身份验证	你的 upapi_ API 密钥	使用你的 upAPI 账户登录（OAuth）
运行位置	你的机器	upAPI
最适用于	脚本、CI、可自托管 Agent	Claude、IDE，以及任何支持远程 MCP 的客户端

两者提供相同的工具和架构，并使用同一份配额计费。

托管方式——无需安装

将支持远程服务的任意 MCP 客户端指向：

https://app.upapi.io/api/mcp

客户端会引导你在浏览器中登录 upAPI；无需复制密钥。使用 Claude Code：

claude mcp add --transport http upapi https://app.upapi.io/api/mcp

本地方式——API 密钥

前往 app.upapi.io → API Keys 创建密钥，然后：

claude mcp add upapi -e UPAPI_API_KEY=upapi_xxx -- npx -y @upapi/mcp

Claude Desktop（claude_desktop_config.json）、Cursor 和 Windsurf 使用相同的 JSON 配置：

{
  "mcpServers": {
    "upapi": {
      "command": "npx",
      "args": ["-y", "@upapi/mcp"],
      "env": { "UPAPI_API_KEY": "upapi_xxx" }
    }
  }
}

变量
UPAPI_API_KEY	必填	upapi_ 密钥
UPAPI_BASE_URL	可选	网关源站，默认为 https://api.upapi.io
UPAPI_TOOL_MODE	可选	compact（默认）、directory、claude 或 full——参见 Tools

密钥不会在本地验证——只检查是否存在，因此如果密钥缺失，会立即显示易懂的错误消息，而不会等到工具调用时才出现难以解释的 401 错误。密钥是否有效、已过期或超出配额，由网关负责答复；对于每台机器上的调用方，这都是唯一负责回答这些问题的地方。

工具

托管端点默认提供精简工具表：两个元工具，加上少数始终可用的操作，总共只有几 KB。

工具	功能
search_ops	按意图查找操作 — 返回 slug、描述、参数和配额消耗
call_op	按 slug 运行一个操作：{ "slug": "github-repo.get", "input": { … } }

每轮都会重新发送工具表作为上下文，因此每个操作对应一个工具，会让每轮增加数十 KB 的 JSON Schema，并使工具表大到足以明显降低工具选择质量。随着目录不断增长，search_ops + call_op 仍能保持精简。web-search.post、github-repo.get 和 wikipedia-article.get 会作为完整工具保留在工具表中，因此常见情况无需额外进行发现往返。

还有另外两种工具表。?tools=full 会为每个操作提供独立工具：

claude mcp add --transport http upapi 'https://app.upapi.io/api/mcp?tools=full'

?tools=directory 会提供一组经过筛选的 11 个具名工具，对应旗舰操作 — 网页转 Markdown、截图、HTML 转 PDF、PDF 文本、OCR、转录、GitHub 仓库、npm 包、Wikipedia、货币 — 并分别列出读取工具和写入工具，不含 call_op。这正是 AI 目录审核标准要求的形式（使用带目标参数的万能调度器会被拒绝，宣传抓取来源的列表也会被拒绝；因此 Maps 三件套和网页搜索仍可调用，但不会列在其中），也是 Claude Desktop Extension 随附的形式。?tools=claude 对 upAPI 自行计算的 8 个操作采用相同形式（网页转 Markdown、截图、HTML 转 PDF、PDF 文本、OCR、转录及其结果、文本分析） — 即 Claude 连接器列表。本地 stdio 服务使用 UPAPI_TOOL_MODE 接受相同的模式名称，默认为 compact — 与托管端点默认提供的几 KB 精简形式相同。full 仍然可用（UPAPI_TOOL_MODE=full），作为回滚选项，供已按该服务过去默认采用的每个操作对应一个工具的形式配置的客户端使用。

每种模式都能访问完全相同的操作 — 模式只改变对外公布的内容，不会改变允许执行的内容。所有模式中的每个工具都带有 readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint，这些提示根据工作器实际执行的操作生成，而不是根据 slug 的动词后缀生成。操作以其 slug 命名，将 . 和 - 替换为 _（web-search.post → web_search_post），并公布操作实际使用的 JSON Schema（格式、边界、默认值、可空性），因为该 Schema 是根据工作器自身模型生成的，并未经修改直接传递。

托管服务在所有模式下都能访问整个公开目录；自 2026-09-26 起，不再隐藏任何类别。本地（stdio）服务和 Desktop Extension 会在下一次发布时跟进：已发布的 0.2.0 包含 63 个操作，但在 directory 模式下仍会隐藏 Social Media 和 Utility。

directory 模式只会改变对外公布的内容 — 即公开列表（如 Claude Desktop Extension）展示的精选旗舰工具集。

描述中包含配额消耗，因此 Agent 可以据此规划：

搜索网页……upAPI 操作 web-search.post（搜索）。每次调用消耗 25 个每月配额单位。

操作失败时会作为正常工具结果返回，包含 isError: true，且文本以 upAPI 的公开错误代码开头 — RATE_LIMITED、INVALID_INPUT、UPSTREAM_UNREACHABLE。发生速率限制时，还会说明需要等待的秒数。操作失败不会中断会话。

特意不声明 outputSchema：MCP 要求声明了该 Schema 的服务返回匹配的 structuredContent，而这些输出描述的是实时第三方负载。一个意外的 null 就会让成功的调用变成协议错误。

在 Mastra 中使用

这些工具可直接用于 Mastra Agent，无需在中间使用 MCP 传输。@mastra/core 和 @mastra/mcp 是可选的对等依赖项——请自行安装，并从 /mastra 子路径 导入绑定。此软件包中的其他部分都不会与 Mastra 交互，因此直接执行 npm i @upapi/mcp（以及基于它构建的桌面扩展包）仍能保持轻量。

import { Agent } from '@mastra/core/agent';
import { createGatewayCaller } from '@upapi/mcp';
import { createUpapiTools } from '@upapi/mcp/mastra';

const agent = new Agent({
  name: 'researcher',
  instructions: 'Research topics using upAPI.',
  model: /* … */,
  tools: createUpapiTools({
    caller: createGatewayCaller({ apiKey: process.env.UPAPI_API_KEY! }),
  }),
});

当 Agent 只应看到目录中的一部分内容时，可使用 filter 缩小表的范围：

createUpapiTools({
  caller,
  filter: (op) => op.category === 'Search',
});

createUpapiMcpServer — 默认启用 Code Mode

createUpapiMcpServer 会构建一个 Mastra MCPServer（@mastra/mcp，也是可选的对等依赖项）。其 默认工具面为 Code Mode：使用 search_tools + execute_typescript，而不是为每项操作 提供一个工具——在完整的 99 项操作目录中测得，tools/list 从 111,016 字节降至 1,069 字节（99 个工具 → 2 个），因为表的大小不再随目录增长。

import { createGatewayCaller } from '@upapi/mcp';
import { createUpapiMcpServer } from '@upapi/mcp/mastra';

const server = createUpapiMcpServer({
  caller: createGatewayCaller({ apiKey: process.env.UPAPI_API_KEY! }),
});

await server.startStdio();

• search_tools({ query? }) 可查找此连接能够访问的操作，并以 declare function external_<name>(...) TypeScript 签名的形式返回。
• execute_typescript({ code }) 会在隔离的 QuickJS 沙箱 （@mastra/quickjs，另一项可选的对等依赖项——不需要原生二进制文件，除注入的 external_* 函数外，无法访问文件系统、网络或进程）中运行一段简短的 TypeScript 程序。使用 Promise.all 将多个操作合并为一次往返，而不是每项操作都单独调用工具。30 秒后终止。如果程序在未等待 external_* 调用的情况下计算超过 1.5 秒，或者在所有此类计算阶段中累计计算时间超过 5 秒，就会因沙箱与进程处理的所有其他请求共享 Node 事件循环而停止执行，并返回 CPU_BUDGET_EXCEEDED: ...。必须在其旁边安装 quickjs-emscripten 0.31.0（这是 @mastra/quickjs 0.1.1 实际解析到的确切版本）。两者会在首次调用 execute_typescript 时加载，因此从不调用它的服务（或使用 full 工具面的服务）无需安装这两个依赖项。

每次 external_* 调用都会解析为与 full 工具面（如下所述）调用的完全相同的 createUpapiTools(options) 工具对象——没有第二条身份验证路径。被拒绝或失败的操作调用会在沙箱内 作为抛出的 Error("<CODE>: <message>") 呈现，因此来宾程序自己的 try/catch 可以检查代码并据此分支处理；不符合操作输入架构的参数也会以同样的方式抛出 INVALID_INPUT: <details>。这与格式错误的 execute_typescript 输入不同，后者会在沙箱启动之前直接导致调用失败。

设置 MCP_TOOL_SURFACE（或传入 surface）可更改公布的内容：

值	公布内容	适用场景
codemode （默认）	search_tools + execute_typescript	任何能编写几行 TypeScript 的模型
full	每项操作一个工具——当前的 createUpapiTools 表	回滚开关，或已基于此工具面构建的客户端
both	两种工具面的并集	在过渡期间测试或迁移某一种工具面

MCP_TOOL_SURFACE=full node my-server.js   # one tool per operation, the pre-Code Mode shape

createUpapiMcpServer({ caller, surface: 'full' }); // same thing, set in code instead of env

只要工具表中包含 codemode 工具（codemode 和 both），服务器上的 instructions 就会自动附带 Code Mode 契约——否则模型不会得到提示，知道要针对 search_tools/execute_typescript 编写 TypeScript。

构建自己的服务

caller 是工具表唯一未提供的内容，因此相同的工具可以通过不同传输方式运行：

import { startUpapiStdioServer, type Caller } from '@upapi/mcp';

const caller: Caller = async (slug, input) => {
  // resolve with the operation's output, or throw
  // { code, message, status?, retryAfterSeconds? }
};

await startUpapiStdioServer({ caller, mode: 'directory' });

对于符合 Web 标准的 Request/Response 服务（Next.js 路由、Worker、Hono），请从 /http 子路径导入处理程序——app.upapi.io/api/mcp 就是通过这种方式构建的：

import { handleUpapiMcpRequest, type Caller } from '@upapi/mcp/http';

await handleUpapiMcpRequest(request, {
  caller,
  // mode defaults to the request's own `?tools=` parameter (compact unless `full`/`directory`)
  canExecute: true, // false hides every executable tool and refuses a call to one
  canSearch: true, // false hides `search_ops`
});

canExecute / canSearch 用于让宿主将自身的授权规则应用到工具表上——upAPI 会将它们映射到访问令牌的 ops:execute 和 ops:read 作用域。两者默认均为 true，因此不使用作用域模型的宿主不会受到影响。

在打包或通过文件追踪进行部署时，优先使用该子路径，而不是包根入口：它只会引入 MCP SDK，而根入口还会引入 stdio 服务。两者都不会引入 Mastra——这些绑定位于 @upapi/mcp/mastra 后，正是为了让从不运行 Mastra Agent 的构建不会接触到 @mastra/core。

相关内容

• @upapi/sdk — 类型化的 HTTP 客户端，以及本包工具表所依据的操作目录
• upapi.io/docs — 操作参考

开发工作所在之处

本仓库是已发布的 @upapi/mcp 所在之处：npm 安装的就是这里的内容，也欢迎在此提交问题和拉取请求。工具表源自 @upapi/sdk 中的操作目录，而该目录由 upAPI 的私有操作定义生成并自动同步——因此工具集会随上游变化。这些文件中的服务、外观层、错误映射和测试均为手写代码，也是需要修改的代码。