efficjump/hi-mcp

# HiMCP [](https://github.com/efficjump/hi-mcp/actions/workflows/ci.yml) [](LICENSE) [](#项目状态) **将经过审查的 API 契约转化为已验证的 MCP 工具。** HiMCP 将 OpenAPI 3.x 文档和声明式 HTTP manifest 编译为内容寻址的 release，然后仅通过 Model Context Protocol (MCP) stdio 提供操作员批准的操作。可执行的 HTTP 行为是确定性地派生出来的，并在使用前进行验证。可选的模型辅助可以改善语义元数据，但它不能更改目的地、身份验证、请求绑定或强制执行的风险策略。 ## 从源码快速开始 HiMCP 目前通过此源码仓库分发。以下命令假定环境为 Node.js 22 或更高版本，并且已检出并构建了源码。Corepack 会选择该仓库声明的 pnpm 版本。 ``` git clone https://github.com/efficjump/hi-mcp.git cd hi-mcp corepack enable pnpm install --frozen-lockfile pnpm build pnpm web ``` 打开 `http://127.0.0.1:4173`。设置控制台仅限环回访问，不得通过反向代理或公共托管服务暴露。`HIMCP_WEB_PORT` 用于选择其他环回端口，而 `HIMCP_WEB_DATA_DIR` 用于选择受管制的工件目录。 ## HiMCP 的功能 ``` flowchart LR source["OpenAPI 3.x or HTTP manifest"] --> registry["Dynamic source adapter registry"] registry --> normalized["Normalized API document"] normalized --> baseline["Deterministic capability baseline"] baseline --> semantic["Optional semantic enrichment"] catalog["Live model catalogues"] --> semantic baseline --> verifier["Deterministic verifier"] semantic --> verifier verifier --> release["Content-addressed release"] release --> profile["Reviewed connection profile"] profile --> mcp["MCP stdio runtime"] mcp --> engine["Policy-enforced HTTP engine"] engine --> api["Reviewed upstream API"] ``` - 源注册表会选择唯一兼容的 adapter，或接受显式的 adapter ID。内置 adapter 支持 OpenAPI 3.x 和 HiMCP HTTP manifest。 - 可移植的 Capability IR 将源解析、语义增强、验证、MCP 传输和 HTTP 执行分离开来。 - 可选的语义提供程序动态发现其活跃的模型目录。模型输出仅限于名称、描述、意图、示例和 schema 标注。 - 验证器使用规范的指纹绑定源来源、可执行契约、风险策略和 release 标识。 - 本地控制台允许操作员在导出前审查确切的操作、来源、凭证环境变量名称和确认策略。 - 运行时验证 MCP 输入和上游响应，仅在执行时解析凭证，阻止非公开目的地，并默认拒绝重定向。 仅当某个已注册的 adapter 具有唯一获胜探测时，自动源检测才会成功。未知或模棱两可的输入会安全失败（fail closed）；当自动化必须明确无歧义时，请使用显式的 `--source-type`。 ## 支持范围 | 区域 | 当前支持 | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | API 源 | OpenAPI 3.x 和声明式 HiMCP HTTP manifest | | 执行 | 经过审查的 HTTP(S) 操作，包含已验证的请求和响应契约 | | MCP 传输 | 本地 stdio | | 凭证 | 基于环境的 API key、Basic/Bearer 凭证，以及现有的 OAuth/OIDC Bearer token | | 模型使用 | 可选的、与提供商无关的语义元数据增强 | | 本地控制台 | 仅限环回的源分析、操作审查、连接审查和描述符导出 | | 不支持 | 远程或多租户控制台、OAuth 生命周期、multipart、流式传输、原生 gRPC、WebSocket、任意 SDK 或代码执行，以及发布者证明 | HTTP manifest 可以表示 REST 风格的调用、基于 HTTP 的 GraphQL、显式的 SOAP/XML 请求、表单或 JSON body、文本，以及规范的 base64 请求字节。不支持的传输会被拒绝，而不是通过任意代码路由。 ## 编译并连接 根目录的 `pnpm himcp` 命令运行已构建的 CLI。将生成的 release、profile、preset 和启动器描述符保存在 `.himcp/` 下；该目录会被 Git 忽略。 ``` mkdir -p .himcp/quickstart pnpm himcp analyze \ examples/customer-support/openapi.yaml \ --source-type auto pnpm himcp compile \ examples/weather-api/http-manifest.yaml \ --source-type http-manifest \ --output .himcp/quickstart/weather.release.json pnpm himcp validate \ .himcp/quickstart/weather.release.json \ --source examples/weather-api/http-manifest.yaml \ --source-type http-manifest ``` 只有在审查了每个确切的来源和身份验证要求后，才创建连接配置文件： ``` pnpm himcp connection create \ .himcp/quickstart/weather.release.json \ --name "Weather API" \ --approve-origin https://weather.example.com \ --output .himcp/quickstart/weather.connection.json pnpm himcp connection export \ .himcp/quickstart/weather.connection.json \ --output .himcp/quickstart/weather.mcp.json ``` 该 profile 包含凭证环境变量名称，绝不包含凭证值。通过 MCP 宿主或 secret manager 提供 `connection create` 报告的变量，将导出的 `mcpServers` 对象合并到宿主配置中，然后重启宿主。 导出的描述符包含机器本地的可执行文件和 profile 路径。请将它们视为私有的机器本地工件：不要提交、发布或发送给其他用户。在每台目标机器上生成新的描述符。 在替换之前，将现有的已验证 release 与当前源进行比较： ``` pnpm himcp diff \ .himcp/quickstart/weather.release.json \ examples/weather-api/http-manifest.yaml \ --source-type http-manifest \ --fail-on breaking \ --json ``` `--fail-on breaking` 会在删除能力、可执行文件或 schema 发生更改，以及安全审查发生更改时失败。`--fail-on any` 还会在添加和仅元数据的更改时失败。 包含的示例宿主仅用于文档说明，支持编译和发现，但不支持成功的上游执行。 ## 本地 Web 控制台 控制台提供一个可审查的工作流程： 1. 粘贴或上传 API 契约，并选择自动或显式的 adapter 发现。 2. 审查规范化的操作、诊断、目的地和身份验证元数据；仅包含应成为 MCP 工具的操作。 3. 注册一个完全包含该已审查子集的已验证 release。 4. 批准每个确切的来源、凭证环境变量名称和确认策略。 5. 导出一个与产品无关的 `mcpServers` 描述符。 大型操作列表使用稀疏选择状态和虚拟渲染，而不会更改批量选择的语义。确切的选择预设是不可变的白名单，绑定到一个分析指纹；更改的契约会使旧的预设过期，而不是默默地选择新操作。契约比较是只读的，永远不会更改当前的选择。 阅读完整的 [Web 控制台使用指南](docs/usage-guide.md)。还提供 [韩语版本](docs/usage-guide.ko.md)。 ## 安全与隐私 切勿将凭证、客户数据、私有示例或内部 URL 放在 API 源或语义提供程序配置中。从源派生的描述、schema、默认值和示例可能会保留在 release 中，并且当启用语义编译时，可能会向配置的提供程序披露。 - Profile 存储的是凭证环境变量名称，而不是凭证值。 - `.himcp/` 下生成的文件仍可能包含 API 来源、操作 ID、指纹和机器本地路径。请将它们保密并排除在版本控制之外。 - 语义提供程序模块是受信任的进程内可执行代码。本地模块需要显式选择加入（opt-in）以及入口文件的 SHA-256 完整性值。 - 控制台是单一操作系统用户的设置界面，而不是远程授权边界。 - 默认执行策略仅允许已审查的 HTTP(S) 来源和公共网络目的地，验证每次尝试的 DNS，并拒绝重定向。 - 除非嵌入环境提供批准，或者操作员明确记录了粗略的进程范围启动器批准，否则需要确认的工具将保持阻止状态。 在连接生产系统之前，请阅读 [安全模型](docs/security-model.md)。请通过 [SECURITY.md](SECURITY.md) 中的流程报告漏洞，而不是通过公开 issue。 ## 可选的语义编译 确定性编译是默认设置。语义编译需要同时使用 `--semantic` 和一个显式配置文件。配置的提供程序工厂会发现其当前的模型目录并接受结构化生成请求；HiMCP 不依赖于固定的模型供应商或模型名称。 将 `.himcp.example.yaml` 复制到一个被忽略的本地配置文件中，将提供程序模块作为可执行代码进行审查，将提供程序凭证保存在具备密钥感知能力的环境中，并遵循 [语义提供程序指南](docs/provider-plugins.md)。 ## 项目状态 HiMCP 是一个早期 alpha 阶段的工程项目。当前的版本有意将显式契约和安全失败（fail-closed）行为置于协议广度之上。 目前的限制包括： - 仅限 HTTP 执行；无原生 gRPC、WebSocket、仅限 SDK 或任意代码的后备。 - 不支持 multipart 请求、流式响应保留或二进制响应保留。 - 仅限本地 stdio MCP 传输。 - 仅限基于静态环境的凭证材料；无 OAuth 发现、获取或刷新。 - 标准配置文件启动器中没有交互式批准回调。 - 没有加密的发布者签名或证明。 - 语义提供程序在没有沙盒的情况下在进程中执行。 ## 文档 - [使用指南](docs/usage-guide.md) - [架构](docs/architecture.md) - [安全模型](docs/security-model.md) - [HTTP manifest 指南](docs/http-manifest.md) - [语义提供程序插件](docs/provider-plugins.md) - [架构决策](docs/adr) ## 开发 ``` corepack enable pnpm install --frozen-lockfile pnpm format:check pnpm typecheck pnpm test pnpm build ``` CI 工作流在受支持的 Node.js 版本上验证相同的格式化、类型检查、测试和构建边界。在提议更改公共契约或信任边界之前，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 HiMCP 采用 [Apache-2.0](LICENSE) 许可证。

标签：API, GNU通用公共许可证, Lerna, MCP, MITM代理, Node.js, OpenAPI, SOC Prime, 开发工具, 策略执行, 自动化攻击