shipMCP (Lin Ysssss)

ShipMCP

   

将任何OpenAPI规范转换为您可以实际发布的可运行的MCP存储库。

ShipMCP采用现有的REST API并生成 可编辑的TypeScript MCP仓库 已经有了auth预设、测试、Docker、CI和可用的README。

OpenAPI输入。可运行MCP仓库输出。

从一个OpenAPI文件到可运行的MCP仓库只需几秒钟。

如果ShipMCP为您节省了一天的MCP布线时间，请启动仓库。

最佳

• 已经拥有OpenAPI规范的团队
• 想要可编辑、可自托管MCP代码的开发人员
• 从一开始就需要身份验证、测试、Docker和CI的API

非卖品

• 还没有OpenAPI规范的团队
• 寻找托管无代码构建器的人
• 今天需要OAuth浏览器流或GraphQL开箱即用的项目

ShipMCP用于从您已经拥有的API中运送MCP仓库。

在30秒内尝试ShipMCP

首先验证一个真实的规范：

node packages/cli/src/index.js validate examples/specs/petstore.yaml

如果看起来不错，接下来生成一个可运行的仓库 node packages/cli/src/index.js generate examples/specs/petstore.yaml --out sandbox/petstore-preview --yes.

为什么人们会这样做

• 大多数团队已经有了API。他们不想再次手动连接MCP工具、请求映射、身份验证、Docker、CI、测试和文档。
• ShipMCP为您提供您自己的代码。它不是一个托管的黑匣子，也不是一个仅供演示的生成器。
• 大型规范仍然可用，因为生成可以通过标签、方法、路径、操作ID、状态代码、响应内容类型和弃用操作进行过滤。

手动MCP接线很昂贵

大多数团队不需要另一个MCP演示。他们需要停止围绕他们已经拥有的API重建相同的粘合代码。

无ShipMCP

• 手动连接MCP工具
• 将参数和请求体映射到HTTP调用
• 添加身份验证处理
• 脚手架试验
• 添加Docker和CI
• 编写第一个README和设置说明

使用ShipMCP

• 运行一个generate命令
• 查看生成的TypeScript仓库
• 根据需要调整名称或身份验证
• 从真实的项目结构中提交和发布

ShipMCP不会删除审核。它消除了重复的设置工作。

你得到了什么

给定一个OpenAPI文件，ShipMCP会创建一个这样的仓库：

my-api-mcp/
  src/
    server.ts
    client.ts
    tools.ts
  tests/
    smoke.test.ts
    api.test.ts
  openapi/
    source.json
  .env.example
  Dockerfile
  README.md
  .github/workflows/ci.yml
  package.json
  tsconfig.json

该输出旨在进行审查、编辑、提交和发布。

快速开始

验证规范：

node packages/cli/src/index.js validate examples/specs/petstore.yaml

生成可运行的MCP仓库：

node packages/cli/src/index.js generate examples/specs/petstore.json --out sandbox/petstore-mcp --yes

运行本地检查：

npm test
node packages/cli/src/index.js doctor

ShipMCP实际生成什么

给ShipMCP一个OpenAPI文件。取回一个可运行的仓库，您可以查看、编辑和发布。

输入：

examples/specs/petstore.yaml

命令：

node packages/cli/src/index.js generate examples/specs/petstore.yaml --out sandbox/petstore-preview --yes

输出：

petstore-preview/
  src/
    server.ts
    client.ts
    tools.ts
  tests/
    smoke.test.ts
    api.test.ts
  openapi/
    source.yaml
  .env.example
  Dockerfile
  README.md
  .github/workflows/ci.yml
  package.json
  tsconfig.json

生成 src/server.ts 摘录：

const server = new McpServer({
  name: "acme-petstore-api",
  version: "0.1.0"
});

for (const tool of generatedTools) {
  server.tool(tool.name, tool.inputSchema, async (input) => {
    const response = await callApi(tool, input);
    return {
      content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
    };
  });
}

const transport = new StdioServerTransport();
await server.connect(transport);

可编辑。可审查。可发货。

为什么ShipMCP不同

• 不是玩具发电机。 ShipMCP生成了一个已经包含测试、Docker、CI、env脚手架和README的仓库。
• 不是托管建筑商。 输出是本地的、可编辑的、可审查的和可自托管的。
• 不是大规格的全部或全部。 您可以在创建仓库之前缩小生成范围。
• 专为现代OpenAPI现实而构建。 支持JSON和YAML，本地引用有效，处理可为null的类型数组，规范化标量多类型数组，以及类似记录 additionalProperties 以干净的方式生成。

为真正的OpenAPI规范而构建

ShipMCP已经处理了不止一个玩具单文件宠物店流。

• JSON和YAML现在都可以使用。 您可以从任何一种格式生成，而无需更改工作流。
• 支持本地参考。 参数、请求体和模式可以通过以下方式解析 #/components/....
• 现代OpenAPI 3.1边缘案例已经涵盖。 可为空的类型数组和标量多类型数组被规范化为可用的Zod输出。
• 在生成之前，可以缩小大规格。 响应感知、路径、标签、方法和操作过滤器使生成的MCP表面可审查。
• 输出未锁定到一个传输。 ShipMCP可以同时生成 stdio 和 http MCP今天回购。

您现在可以查看此仓库中的具体示例：

• examples/specs/petstore.yaml ->基线YAML支持加上本地 $ref 决心
• examples/specs/compatibility-nullable.json ->可空类型数组和清洁器 additionalProperties 处理。
• examples/specs/response-aware-filter.json ->响应状态和响应内容类型过滤。
• examples/specs/multi-type-array.json ->标量多类型数组规范化，例如 type: ["string", "integer"].

今天支持

ShipMCP目前支持：

• 开放API 3.x
• 本地或远程规格输入
• JSON和YAML输入
• TypeScript MCP服务器输出 stdio 和 http
• API Key 和 Bearer Token 身份验证预设
• 生成的测试、Docker和GitHub操作CI
• 本地 #/components/... $ref 参数、请求体和模式的解析
• 对象和数组的结构化Zod输入生成
• OpenAPI 3.1可以为null和标量的多类型数组，例如 type: ["string", "null"] 和 type: ["string", "integer"]
• 改进的 additionalProperties 处理类似记录的地图和混合对象
• 关键stdio和HTTP输出的生成器快照覆盖率
• 按标签、方法、路径、操作ID、响应状态、响应内容类型和弃用状态进行筛选

显然不在v0.1中：

• OAuth浏览器流
• 图查询语言
• GUI构建器
• 托管代
• 多语言输出

过滤是一项功能，而不是事后的想法

真正的OpenAPI规格很快就会变大。如果ShipMCP从大型内部API发出每个操作，则生成的MCP表面会变得嘈杂且难以审查。

ShipMCP已经支持实用的控制层，例如：

• --include-tags pets,admin
• --exclude-tags internal
• --include-methods get,post
• --exclude-methods delete
• --include-paths /pets*,/billing/*
• --exclude-paths /admin/*
• --include-operation-ids listPets,getPet
• --exclude-operation-ids create*,delete*
• --include-response-statuses 200,201,2*
• --exclude-response-statuses 4*,5*
• --include-response-content-types application/json,application/*+json
• --exclude-response-content-types image/*,application/octet-stream
• --deprecated-only
• --exclude-deprecated

支持路径、操作ID、响应状态和响应内容类型筛选器 * 通配符。

更多示例

使用本地引用从YAML生成示例：

node packages/cli/src/index.js generate examples/specs/petstore.yaml --out sandbox/petstore-yaml --yes

生成HTTP MCP仓库：

node packages/cli/src/index.js generate examples/specs/petstore.json --out sandbox/petstore-http --transport http --yes

仅生成 /pets* 排除匹配操作ID时的路径：

node packages/cli/src/index.js generate examples/specs/petstore.json --out sandbox/petstore-focused --include-paths /pets* --exclude-operation-ids create* --yes

仅生成具有JSON样式响应的操作：

node packages/cli/src/index.js generate examples/specs/response-aware-filter.json --out sandbox/response-aware-json --include-response-content-types application/json,application/*+json --yes

如果你的规格不合格，那就是路线图信号

当真正的规格达到时，ShipMCP是一个更好的开源项目。

通过以下方式打开问题：

• 规格不合格或重复性降低
• 电流输出
• 预期产出
• 身份验证要求（如相关）

该回购有一个自然贡献面：

• 现实世界规范兼容性修复
• 身份验证预设
• 命名和规范化规则
• 生成器模板
• 示例API
• 文档和启动资产

文档

• 产品需求文档
• 项目计划
• 问题积压
• 建筑
• CLI-UX
• 启动副本
• Bootstrap发行说明
• 自动化操作手册
• 路线图
• 贡献

Monorepo布局

packages/
  cli/
  generator/
  runtime/
examples/
  specs/
docs/

近期重点

1. 提高现实世界中OpenAPI的兼容性，超越本地参考。
2. 扩展区分联合、对象和数组多类型数组以及其余附加Properties边缘情况的模式规范化。
3. 将响应感知选择扩展到状态代码和已弃用的过滤器之外。
4. 添加更多展示示例以供发布。
5. 加强生成的运行时错误处理。

许可证

麻省理工学院