Apiosk

Apiosk MCP

@apiosk/mcp 3.0.0 将 Apiosk 的 Ask 工作流带到 Claude、Codex 和其他 MCP 宿主：提出问题、比较匹配的来源、查看输入和总计、批准该请求，并检查已保存的结果。它使用现有 Gateway 进行发现、规划、定价、执行和取证。

MCP1 卡片 URL、连接身份、令牌格式和缓存的 Ask 工具签名仍保持兼容。兼容性操作仅对卡片开放；新的模型连接仍会优先看到 Ask。新旧审批调用共用同一条持久化审批记录。

默认行为是按问题范围发现来源，不提供全局“浏览目录”流程。例如，对于“What does ASML do?”，应先使用该问题调用 apiosk_ask 并展示匹配的来源；模型的一般知识不属于 Apiosk 的结果。

此仓库是 obcraft/apiosk-mcp 的权威实现。带版本的源代码和清单不能证明此版本已部署、发布或安装到宿主中。

Ask 交互和嵌入式组件

该服务提供 36 个公开工具和 6 个私有组件操作、已保存请求资源和一个 Ask 提示词。实际的 App Ask React 组件和设计令牌位于 src/ask-page/，并编译到独立的嵌入式资源中。本地测试器加载的也是同一资源。src/ask-ui/ 保留了原始 MCP 传输和兼容渲染器；每项操作仍使用持久化的已保存请求和审批日志。

源发现使用 App 的筛选、去重和提供方排序规则。提供的端点描述信息会补充匹配的来源，但不会添加无关的目录条目。账户显示货币来自 Gateway 的只读 /v2/display-context；报价中的原子金额保持不变。编辑源文件后，运行 npm run build:ask-page 重新构建嵌入式包。

手动选择来源时，会使用 App 中完全相同的输入值为所选原生端点做好准备。已连接的客户端使用 /v2/ask/source/prepare；即使连接已有常设支出规则，该操作也需要明确审批。MCP 会将这些已保存报价合并为一个待审核的最高金额；准备操作不会购买数据。

MCP Apps 和兼容 ChatGPT 的元数据会标识嵌入式资源。模型可见的结果包含精简的来源标识符、状态、所需输入和确切的审批信息。完整组件数据通过 _meta.apiosk_card_data 单独传递，因此大型来源架构和原始响应树不会占满模型上下文。可通过结果和证据工具获取已保存的依据。

支持嵌入式组件的宿主可以显示交互式卡片。仅支持文本的宿主会收到结构化结果，并使用公开工具。支持情况和渲染效果仍取决于宿主；通过本地测试并不能证明已安装的 Claude、Codex 或 ChatGPT 会接受这些内容。只读 HTML 导出与交互式卡片相互独立。

交互	工具
Ask 并检查匹配的来源	apiosk_ask、apiosk_sources
编辑来源输入并准备总金额	apiosk_prepare
审核并明确批准确切报价	apiosk_approve
查看进度、刷新价格、提供选项或补充缺失输入	apiosk_status、apiosk_requote、apiosk_continue
重试中断的发现流程并调整任务选项	apiosk_retry_search、apiosk_task_options、apiosk_source_selection、apiosk_analysis_quote
已保存的答案、证据、页面、下载内容和对话	apiosk_result、apiosk_evidence、apiosk_result_page、apiosk_artifact、apiosk_chats
使用已购买的证据进行后续查询	apiosk_follow_up
已连接 App 的操作和定期检查	集成／操作审核工具、原生定期工具和 apiosk_schedule_handoff

apiosk_ask 默认使用 mode: "sources"。自动规划可通过 mode: "automatic" 启用。准备操作绝不会批准购买。在授权执行前，请检查返回的货币、最高总金额、来源、缺口、有效期和审批 ID。显示的选项采用与 Ask 页面相同的可购买性筛选规则；发现元数据和来源选项不是已购买的发现结果。

结果会保留来源日期、引用、覆盖范围和缺口，包括有意义的 0 和 false 值。本地筛选、排序、图表／表格视图、已保存页面和导出都会复用已保存的数据。后续查询会尽可能使用已购买的证据；如需新数据，则会创建单独审核的请求。

从此检出版本运行

需要 Node.js 22.16 或更高版本，以及经过授权的 Apiosk 连接。在此工作区中，规范目录为 /Users/olivier/Documents/Apiosk/Production/Main/mcp。

cd /Users/olivier/Documents/Apiosk/Production/Main/mcp
npm ci
npm run check
npm test

使用私有环境或本地 .env 中现有的 Apiosk 凭据；不要将凭据放入已提交的示例中。运行时入口会读取环境变量。若要显式加载 .env，请使用 Node 的 --env-file 选项。

入口	用途
node index.mjs / npm run start:stdio	本地 stdio MCP；使用已配置的连接令牌。apiosk、apiosk-mcp 和 apiosk-mcp-server 软件包命令均使用此入口。
node server.mjs / npm start	规范的托管 HTTP 服务，默认端口为 3000，提供 OAuth 元数据、注册、授权和令牌路由。也保留经过身份验证的旧版 SSE 端点。
node bin/mcp-2.mjs --http --host 127.0.0.1 --port 3012	用于本地测试的最简 bearer 令牌 HTTP 传输。此兼容性文件名仅供内部使用；此入口不提供托管 OAuth 流程。

使用私有 .env 运行 stdio：

node --env-file=.env index.mjs

托管服务会保留现有 OAuth 身份和密钥配置。启动服务需要这些设置，包括签名密钥；如果它们位于本地文件中，请使用 node --env-file=.env server.mjs。HTTP 客户端自行对每个请求进行身份验证。服务级令牌绝不会提供给 HTTP 调用方。/health 报告进程健康状况，而非 Gateway 或来源的就绪状态。

本地测试器

测试器运行于 **http://127.0.0.1:3013**，默认使用 http://127.0.0.1:3012/mcp 作为 MCP 端点。在一个终端中启动最简本地 MCP 传输：

node --env-file=.env bin/mcp-2.mjs --http --host 127.0.0.1 --port 3012

在另一个终端中启动测试器：

npm run dev:chat

若要改为测试端口 3000 上的规范托管服务：

MCP_DEV_URL=http://127.0.0.1:3000/mcp npm run dev:chat

测试器会读取此检出版本中的 .env、.env.v2.local 和 .env.dev.local，并优先采用继承的环境变量。它会复用现有的 MCP_DEV_TOKEN 和 OPENROUTER_API_KEY。如果未设置本地 OpenRouter 密钥，它只会从同级目录的 gateway/.env 中读取提供商密钥（依次尝试 OPENROUTER_API_KEY 和 INTENT_API_KEY）。它不会继承 Gateway 执行标志或更改这些凭据。MCP_DEV_PORT、MCP_DEV_URL 和 MCP_DEV_MODEL 可覆盖测试器默认值。设置 MCP_DEV_GATEWAY_URL 可指定自定义 Gateway 事件来源；嵌入式卡片和测试器使用相同的固定来源策略来推送实时状态更新。

提问前，请先连接目标账户。测试器会针对第一个问题调用 apiosk_ask，并渲染与其他主机所提供组件相同的嵌入式组件。首次发现会停留在权威的 Ask 卡片，不会额外生成由模型编写的回答。后续模型续答会收到经过限制的工具结果投影；完整卡片数据仍可供组件使用。模型 API 用量和经批准的来源购买是彼此独立的操作。

连接 Claude 或 Codex

使用 examples/codex.toml、examples/claude-code.mcp.json 或 examples/claude-desktop.json，并保留其他已配置的服务。根据安装位置调整绝对路径，并将令牌保存在私有配置或环境变量中。这些文件仅为示例，不代表已安装的连接。

托管连接器地址仍为 https://mcp.apiosk.com/mcp；本地源代码更改不会更新该部署。Apiosk 插件提供 Ask 优先指令和托管连接定义。server.json、manifest.json 和 dxt.json 描述规范软件包；桌面清单并非已构建或已安装的软件包。

配置和后端边界

变量	含义
APIOSK_GATEWAY_V2_URL	数据／执行 Gateway；默认为 https://gateway.apiosk.com。仅在本地 Gateway 场景下使用回环 HTTP。
APIOSK_GATEWAY_URL	现有的 OAuth Agent Gateway 设置；不会选择数据／执行 Gateway。
APIOSK_CONNECT_TOKEN	用于 stdio 的 Apiosk Agent 连接凭据。
APIOSK_TOKEN	覆盖连接令牌。有效的个人 App 会话 JWT 可启用仅限账户的路由；此服务不会刷新该 App 会话。
APIOSK_WORKSPACE_ID	stdio 工作区。HTTP 调用方使用 x-apiosk-workspace-id。
APIOSK_MCP_STATE_DIR	持久化私有日志目录；默认为软件包中的 .local/state。
APIOSK_MCP_PORT / PORT	HTTP 端口；默认为 3000。
APIOSK_MCP_HOST / APIOSK_MCP_BIND_HOST	监听地址。托管入口默认为 0.0.0.0；仅本地访问时使用回环地址。
APIOSK_MCP_ALLOWED_HOSTS、APIOSK_MCP_ALLOWED_ORIGINS	HTTP 监听器的显式主机／来源控制项。

Gateway 的范围、预算、工作区和功能限制仍具有约束力。在原始任务／审批协议中，组织 API 密钥不能替代 Agent 连接令牌。仅限账户的集成和原生定期操作可能需要有效的 App 会话以及后端启用；app_only 或 public_api_required 响应不能绕过这些要求。

连接令牌使用 /v2/ask/page，该接口会应用 Ask 页面的解释器、验证和来源搜索。App 会话使用原有的 App 路由。两者使用相同的来源筛选、分组、输入值和显示币种。连接后的发现会保留 App 中的匹配项，不会采用较旧公共 API 的解释修正或额外来源扩展；签名搜索仍绑定到账户、连接和工作区。刷新来源会重复使用已保存的解析结果，自动规划则会采用当前显示的搜索结果，而不会再次解析问题。

定期执行需要单独明确审核工作流、计划、目标位置和费用限额。apiosk_schedule_handoff 会提供供宿主调度器使用的说明，并报告 schedule_created: false；它不会创建计划任务。外部应用操作同样需要经过单独审核后才能执行。

保存状态、恢复和部署

日志会以私有文件权限保存私有对话、证据和审批意图，不会保存凭据。对话与 Web 应用的聊天历史表相互独立；可按 ID 导入已授权的 Gateway 任务。状态范围包括 Gateway 和工作区。原始 bearer 调用方的状态按令牌区分；托管的 OAuth 会话在令牌刷新后仍保留其已验证的授权范围。

原子写入和逐请求锁会在分派前记录审批意图。对于结果不确定的购买，不会盲目重放：读取已保存的状态，并使用返回的恢复路径。报价总额是适用于所有服务提供方的支出上限，并非全有或全无的交易。本地磁盘故障会阻止资金转移操作。

托管运行需要持久化日志。Fly 配置会保留现有应用标识，并要求已有的 mcp_state 卷挂载到 /data；在实现共享状态和分布式锁之前，请仅运行 一台机器。请在部署前配置并检查该卷。请参阅部署和发布说明。

推送仓库只会运行检查。部署和发布是单独的手动工作流。测试使用受控的固定数据，不会购买来源数据；本地运行成功并不能证明生产环境中的检索、消息送达、计划运行或宿主连接安装已生效。