MCP-Server-Reference

未受治理的MCP是一种未登记入目的API，位于高一层。

一个小型 Model Context Protocol 服务器，它发布一份静态的 OpenAPI 目录、一份书面契约和一份明确的拒绝清单。它是一个参照接口暴露面——不是平台，也不是 SaaS。

Bruno Carvalho de Aquino，解决方案架构师。

MCP host (Cursor, Claude, …)
        |
        | stdio
        v
+---------------------------+
|  mcp-server-reference     |
|                           |
|  tools  = catalog lookup  |
|  resources = contract     |
|  deny-list = interface    |
+---------------------------+
        |
        | imported modules only
        v
   orders | identity | billing
   (OpenAPI snippets, no fetch)

问题

团队正在以当年接入影子 API 的方式接入 MCP 服务器：一个进程、几个功能强大的工具、没有清单、没有负责人、也没有关于该进程不应做什么的任何书面说明。

一个接受 URL 的工具就是 HTTP 代理。一个接受 shell 字符串的工具就是远程代码执行。一个转储 process.env 的工具就是凭据外泄。协议本身并不会让这些形态变得安全。把它们称为“工具”，只会让它们掩在 API 评审者的视线之外。

Related MCP server: swag

这个仓库是什么

目录是编译进进程的三个实验室 OpenAPI 文档（orders、identity、billing）。规范的 servers[] 使用 .invalid 顶级域。进程从不去获取它们。

这个仓库不是什么

• 不是。Apidex 是产品形态的答案（清单、生命周期、MCP 治理）。本仓库是公开的楔子：一台诚实的服务器，以及一个书面的“不”。

• 不是 MCP 安全网关。 没有 OAuth、没有按主体区分的允许名单、不推发审计日志。那是后续的另一个盒子。

• 不是客户成功案例。 没有编造的服务器数量、令牌数，以及所谓“影子 MCP 降低 N%”。

约束

• Node 20+。 TypeScript 严格模式。没有运行时文件系统遍历。没有 fetch。没有 child_process。

• 工具的输入是封闭的：slugs、HTC 方法、路径模板、拒绝清单枚举。

• billing 是有意弃用的。目录若隐藏离场 API，集成就会随之腐烂。

• Identity 发布的部分不包含密码或令牌端点。受限状态是元数据，不是做样子。

风险说明

这是一张威胁便签，并不是生产环境知产的完整 STRIDE 模型。若把本服务器挂到宿主上，你仍然要信任宿主进程和模型。淡薄化这种信任是网关的活。

本地运行方式

npm install
npm test
npm run typecheck
npm run inspect    # prints the contract JSON
npm run build

stdiio 服务器（宿主拉起的那个）：

npm start
# or, without a prior build:
npm run dev

不要往那个进程里输入内容。MCP 使用 JSON-RPC 在 stdin/stdout 上传。在不同的地方，和宿主聊天。

Cursor / Claude Desktop

{
  "mcpServers": {
    "catalog": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-reference/dist/index.js"]
    }
  }
}

先 build。宿主必须能启动 Node。连接后调用 inspect_contract 或读取 mcp://contract。

冒烟测试，无宿主

npm run inspect

你应当能看到五个工具、四个资源和七条拒绝清单 id。

与 API 治理的关系

OpenAPI 治理早已有词汇表：owner 所有权、生命周期、破坏性变更、deprecation 弃用、“这个操作不公开”。MCP 来了，却把这套词汇忘了。

如果你看到“加不明 CI 的 REST 端点”的 PR 会被拒，那么它也不该让“不加文档 API 的 MCP 工具”的 PR 通过。

这个问题的产品形态——API 和 MCP 服务器的清单、生命周期、审查——is Apidex。本仓库并不实现这些。它演示的是一个目录可以摄取的 factor：一个能描述自己，并解自己拒绝什么的服务器。

我接受的选择

一堆厨房齐全的 demo 只要写入截屏很好看，它也可能教出下一位工程师“就这一次”地加 fetch。我选了一副普通目录，让拒绝清单自己成为焦点。

代价是：你不能用这个服务器去“做X”。这是故意的。执行是另一张契约，与身份有关。

写道

MIT。Copyright (c) 2026 Bruno Carvalho de Aquino。