Fortrip

Fortrip

Fortrip 的公开 Agent 入口集中在一个仓库中：用于搜索酒店、查看实时优惠和订单的 fortrip 命令行工具、所有 Agent 入口共用的契约，以及引导 Agent 使用 Fortrip 的商店页面。目前仅支持酒店。

这里的所有内容都连接到 Fortrip API v1（https://api.fortrip.ai/v1），或托管的 MCP 服务（https://mcp.fortrip.ai/）；使用者均为已在浏览器中通过 OAuth 登录的 Fortrip 用户。

使用 Fortrip

• 通过 Shell，或通过能够使用 Shell 的 Agent： npx -y fortrip <command>。先运行 npx -y fortrip login；CLI 的 README介绍了 命令、登录方式和退出代码。

• 通过 MCP 客户端： 如果客户端支持通过 OAuth 连接远程服务，请连接托管的 MCP 服务 https://mcp.fortrip.ai/； 或运行本地桥接程序 npx -y fortrip mcp。CLI 的 README 提供了 Claude Desktop、Cursor、Codex 和 Claude Code 的配置。Claude 和 OpenAI 插件使用托管服务。

• 作为技能，供能够运行 Shell 命令但没有 Fortrip MCP 工具的 Agent 使用：

  npx skills add FortripEngineering/fortrip --skill fortrip-cli
  

目录结构

路径	内容	发布方式
packages/contract	Fortrip API v1 的契约：限制、路径、请求和响应架构、错误代码、字段规则、MCP 工具和 CLI 命令的规范，以及 Agent 指南。内容仅编写一次，并为 MCP 服务、Claude 技能和 CLI 生成相应内容	npm：@fortrip/agent-contract，随 main 上的 v* 标签发布，并与 fortrip 一起发布
packages/cli	fortrip CLI：通过 Shell 搜索酒店、查看实时优惠、订单和付款链接；还包括本地 MCP 桥接程序（fortrip mcp）和 Agent 指南（fortrip guide）	npm：fortrip，随 main 上的 v* 标签发布，并与 @fortrip/agent-contract 一起发布
plugins/claude	Claude 插件（托管的 MCP 服务 + 静态技能，由程序生成）	在开发者门户中提交；根目录中的 .claude-plugin/marketplace.json 允许 Claude Code 将此仓库添加为插件市场
plugins/openai	ChatGPT / Codex 插件	将压缩包上传到 OpenAI 门户
plugins/registry	MCP Registry 条目	Publish Fortrip to MCP Registry 工作流
skills/fortrip-cli	供能够使用 Shell 的 Agent 使用的技能（由程序生成）	npx skills add FortripEngineering/fortrip --skill fortrip-cli 从 main 读取
scripts	仓库级脚本：generate.ts 用于生成技能，validate.mjs 用于检查列表

开发

Node.js 22 或更高版本，以及 pnpm 11。

pnpm install
pnpm test             # tests of every package, and of the scripts
pnpm generate         # renders the skills from the contract
pnpm generate --check # fails with a diff when a generated file is stale
pnpm build && pnpm validate   # checks the store listings

每个包也都会运行 pnpm typecheck 和 pnpm build。CI 会在 Node.js 22 和 24 上运行类型检查、测试和构建；此外，还会在 Node.js 24 上运行 pnpm generate --check、pnpm validate 和 claude plugin validate --strict，检查 .``、plugins/claude和skills`。

生成的文件

技能文件（plugins/claude/skills/fortrip 和 skills/fortrip-cli 中的 SKILL.md 和 references/planning.md）以及契约中的 src/guide-data.generated.ts 均由程序生成。切勿直接编辑这些文件：请修改 packages/contract/guide/*.md 中的指南片段（或在 scripts/generate.ts 中修改技能的 front matter），运行 pnpm generate，然后提交生成结果。这些片段规定了各个入口要说明的内容；Claude 技能、MCP 指令和 CLI 指南都由这些片段生成，因此内容不会彼此偏离。

发布

Claude 插件

plugins/claude 是一个包含两部分的插件：

• .mcp.json 指向托管的 MCP 服务。在 claude.ai 和 Cowork 中，它会显示在插件的 Connectors 标签页中，用户可在此通过 OAuth 使用 Fortrip 账户登录；Claude Code 则直接连接到该服务。
• skills/fortrip/ 是生成的技能，用于告知 Claude 如何使用这些工具：调用顺序、每间房的入住人数、价格和货币、在付款链接前确认，以及错误处理。references/planning.md 涵盖灵活日期、预算、拆分住宿和多个目的地。

该技能是自包含的：目录不允许插件在运行时获取说明（Software Directory Policy §2F），其验证器也会阻止未固定版本的 npx 启动器，因此 CLI 技能不会放在 plugins/claude 中。如果其中的文件提到 npx、fortrip@latest 或 get_planning_guide，pnpm validate 就会失败。

在开发者门户中提交 plugins/claude 文件夹。使用以下命令检查：

claude plugin validate --strict plugins/claude
claude plugin validate --strict .

第二条命令会检查仓库根目录下的 .claude-plugin/marketplace.json。其中将 plugins/claude 列为插件，因此 npx skills add 能找到与 skills/fortrip-cli 并列的插件技能，Claude Code 也能将此仓库添加为市场。

Claude Code 会让用户使用 plugin.json 中的 version，因此每当 plugins/claude 中有任何更改（包括重新生成技能文本）时，都要更新版本号：措辞调整使用补丁版本；新增行为或组件使用次版本（1.1.0 将插件迁移到了托管的 MCP 服务）；会破坏用户使用方式的更改则使用主版本。目录仅采用首次提交时的列表图标。

CLI 技能

skills/fortrip-cli 是 CLI 的静态指南技能：Agent 可直接从技能中读取命令、调用顺序、登录方式，以及付款链接前应向用户展示的内容。它需要 Node.js 22 或更高版本，且不属于 Claude 目录插件。

npx skills add FortripEngineering/fortrip --skill fortrip-cli

OpenAI 插件

plugins/openai/plugin.json 包含列表介绍文案和审核测试用例，mcp.json 则包含托管服务的 URL。mcp.json 遵循 Agent Plugins 架构（type: streamable-http），而 plugins/claude/.mcp.json 遵循 Claude 的架构（type: http）；两者都指向同一服务。构建上传文件：

cd plugins/openai && rm -f ../../fortrip-openai.zip && zip -rX ../../fortrip-openai.zip plugin.json mcp.json assets

在 OpenAI 门户上传 zip 文件。门户会通过由 mcp.fortrip.ai 提供的 https://mcp.fortrip.ai/.well-known/openai-apps-challenge 验证域名。

MCP Registry

plugins/registry/server.json 将 Fortrip 列为 io.github.FortripEngineering/fortrip，并提供两种连接方式：托管服务（remotes）和 npm 包 fortrip，通过 fortrip mcp 运行（packages；packages/cli/package.json 中的 mcpName 必须与条目的名称一致）。该条目由专属工作流 Publish Fortrip to MCP Registry（.github/workflows/publish-mcp-registry.yml）发布；该工作流仅从 main 运行，并需等待人工批准 mcp-registry 环境。要发布更改，请增加 version（版本号不能降低），将 packages[].version 设为 npm 上的 CLI 版本，合并到 main，然后运行工作流。CLI 发布后，待 npm 上有了新版本，再运行一次工作流。

要弃用旧版本或重新将其设为有效版本，请运行 Set an MCP Registry version's status（.github/workflows/mcp-registry-status.yml），并提供版本号、状态，以及弃用时的消息（状态为 active 时，发布器不接受消息）。该工作流采用相同的仅限 main 分支且须经批准的设置。个人使用 mcp-publisher login github 无法完成此操作：该命令只能获取 io.github.<user>/*，因此组织命名空间需通过此仓库的 OIDC 身份来访问。

Registry 会将服务 URL 绑定到一个名称，因此重命名时，必须先删除旧条目，再发布新条目。

发布

fortrip 和 @fortrip/agent-contract 会以相同版本一起发布。

1. 在 PR 中，将 packages/cli/package.json 和 packages/contract/package.json 中的 version 设为新的 X.Y.Z（在每个包的目录中运行 npm version X.Y.Z --no-git-tag-version），同时将 plugins/registry/server.json 中的 packages[].version 也设为该版本，然后运行 pnpm generate 并提交其更改。CI 通过后，将 PR 合并到 main。

2. 为 main 上的合并提交打标签，并推送该标签：

   git checkout main && git pull
   git tag vX.Y.Z && git push origin vX.Y.Z
   

3. 由人工批准 npm-publish 环境。随后，工作流 publish.yml 通过可信发布机制将两个包发布到 npm（npm 使用 GitHub Actions 的 OIDC 登录，因此 GitHub 中不会存储 npm 令牌），并为它们提供来源证明。

4. 新版本出现在 npm 上后，运行 MCP Registry 工作流（见上文）。

如果标签格式不是 vX.Y.Z 或 vX.Y.Z-rc.N、与任一 package.json 中的 version 不一致，或不在 main 上，工作流就会拒绝该标签。其 build 作业会运行类型检查、测试和构建，并打包两个 tarball；其 publish 作业会在 npm-publish 环境中发布这些 tarball（先发布 @fortrip/agent-contract），不会安装或构建任何内容。标记为 vX.Y.Z-rc.N 的候选版本会使用 next dist-tag 发布，因此 npm install 不会安装它。部分发布后重新运行发布作业时，已在 npm 上的内容会被跳过。

许可证

Apache License 2.0。版权所有 2026 FortripAI, Inc.（见 NOTICE）。2.0.0 之前发布的版本采用 MIT License 发布。本许可证不授予访问 Fortrip 托管服务、酒店库存或第三方数据的权限。

商标

“Fortrip” 和 Fortrip 徽标是 FortripAI, Inc. 的商标。Apache License 2.0 不授予使用 FortripAI, Inc. 商号、商标、服务标记或产品名称的许可，但为合理且惯常地描述软件来源以及再现 NOTICE 文件内容（第 6 节）所必需的情况除外。