cyanheads-mcp-server

---

概述

在 cyanheads 工具集群中找到适合当前任务的 MCP 工具。用通俗语言描述任务，即可搜索所有工具和服务，随后获取说明、连接 URL，以及适用于客户端的安装片段。

工具

工具	描述
cyanheads_search_catalog	根据自然语言查询搜索工具集群中的工具和服务。返回按相关性排序的匹配结果，附带简短摘要和所属服务。
cyanheads_describe_entry	返回指定工具或服务的说明、连接 URL，以及适用于各客户端的安装片段。

功能参考

cyanheads_search_catalog _工具

• query 为 1–500 个原始字符，且必须包含非空白文本；在嵌入和回显前会去除首尾空白。scope 选择 tools（默认）或 servers；可选的 category：research、government、public-data、utility；limit 为 1–1000（默认 5），每次调用最多返回 20 条：当较大的 limit 使当前页之后仍有匹配项时，响应会添加 truncated、shown、cap，以及指出后续页起始偏移量的 notice。
• 结果包含余弦相似度 score（[0, 1]，仅可在同一响应内比较）。工具搜索会附带 servers 汇总，每页含十条条目，以及 serversTotal；未加载的目录会返回可重试的 catalog_empty。
• 使用 offset 分页获取结果，并使用 serversOffset 独立分页获取工具范围的汇总（两者默认均为 0）。后续调用使用相同的 query、scope、category 和 limit，并设置 nextOffset / nextServersOffset；值为 null 表示已无更多结果。每次调用都会使用当前目录，因此分页期间刷新目录可能会改变排序。servers 范围要求 serversOffset: 0，并且不包含汇总字段。
• SIMILARITY_FLOOR（默认 0.3）会在应用 limit 前筛选匹配项。
• 空的 category 字符串会被视为未提供；其他未知的 category 值会被拒绝。

---

cyanheads_describe_entry _工具

• name 为 1–64 个字符，可接受工具名或服务名；名称会自动检测，也可通过 kind 指定。优先匹配完全相同的名称，其次匹配唯一的不区分大小写的名称；输出使用规范名称。client 可选，用于选择 claude-code、cline、codex、cursor、gemini、streamable-http（通用 mcpServers JSON）或 curl。
• server（可选，1–64 个字符）用于指定所属服务：搜索结果中的 name + server 可在任一范围内精确描述对应条目。当多个服务拥有同名工具时，此参数为必填；指定服务名时，必须与该工具所属的服务相同。
• 空的 kind、client 和 server 字符串会被视为未提供。其他未知的 kind 或 client 值会被拒绝。
• 两种类型都会返回连接元数据和安装片段；服务结果还会包含完整的工具清单。已发布的服务会提供本地片段；托管服务还会提供 HTTP 片段。对于仅支持本地连接的条目，client: "curl" 会返回成功的元数据，并通过 installNotice 指明可尝试使用的 stdio 客户端。即使没有片段，必需的环境变量仍会显示。
• 描述来自目录文本；请从已连接服务的 tools/list 获取工具架构。
• 失败时会返回 not_found、ambiguous_kind（设置 kind）、ambiguous_owner（设置 server；错误会列出所属服务），或可重试的 catalog_empty。

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

目录专属功能：

• 每小时在后台刷新目录（CATALOG_REFRESH_SECONDS，默认为 3600）；当 generatedAt 发生变化时，原子替换索引——无需重启
• 空目录、身份冲突的重复项以及无法规范化的向量（维度错误、全零或包含非有限分量）都会在替换索引前导致失败；刷新会保留上一个有效目录。索引前会合并相同的重复项，并发出数量有限的加载时警告；没有工具的服务仍然有效。
• 查询嵌入在请求时通过 @huggingface/transformers 计算；文档嵌入则预先计算、经过 L2 归一化并进行 Matryoshka 截断，随 fleet.json 一起提供。服务在加载时会再次归一化每个文档向量，因此即使目录中的向量偏离单位长度，分数仍保持为余弦相似度；对于偏离超过 1e-4 的向量，会发出数量有限的警告并列出向量名称。
• 嵌入模型会在启动期间预热，且早于 OpenTelemetry 的 HTTP 插桩对 fetch 进行修补——避免在 OTEL 下冷缓存导致模型加载失败
• 支持自描述：cyanheads_describe_entry 会从静态回退记录中解析本服务自身的名称和工具；仅当远程目录中没有本服务条目时才会查询该记录
• CATALOG_URL 可指向任何提供相同架构的端点，用于接入自定义工具集

适合 Agent 的输出：

• 搜索响应会回显实际查询内容、报告限制数量前的匹配总数；没有匹配项时会提供扩大搜索范围的建议；当高于 20 的 limit 被截断至每次调用上限时，会注明可继续查询的偏移量
• cyanheads_describe_entry 返回带判别字段的 result.kind（tool | server），调用方可以根据数据分支处理，而不必解析字符串
• 每个搜索结果都包含用于校准可信度的 score 字段，并提供 servers 汇总，让 Agent 无需再次调用即可查看匹配结果来自哪些服务

入门

公共托管实例

公共实例位于 https://cyanheads.caseyjhand.com/mcp——无需安装。该实例通过 Streamable HTTP 提供服务；每个客户端的配置格式各不相同。

对于 Claude Code：

claude mcp add --transport http cyanheads https://cyanheads.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "cyanheads-mcp-server": {
      "type": "streamableHttp",
      "url": "https://cyanheads.caseyjhand.com/mcp"
    }
  }
}

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "cyanheads-mcp-server": {
      "url": "https://cyanheads.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在“设置” →“连接器”下添加远程服务。

Claude Desktop 安装包

下载 MCPB 安装包，以在本地通过 stdio 安装。该安装包包含 ONNX WebAssembly 推理功能，因此无需依赖特定平台的原生库。首次启动时会下载嵌入模型；之后启动时会复用模型缓存。npm 和 Docker 安装使用原生 CPU 推理。

自托管 / 本地

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "cyanheads-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/cyanheads-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "cyanheads-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/cyanheads-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "cyanheads-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/cyanheads-mcp-server:latest"]
    }
  }
}

使用 Streamable HTTP 时，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/cyanheads-mcp-server.git

2. 进入目录：

cd cyanheads-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env to override any defaults

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod 模式进行验证。每个变量都有合理的默认值——开箱即用时，服务会指向 canonical cyanheads fleet。

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_HOST	HTTP 服务绑定主机	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	MCP 服务挂载的 HTTP 端点路径	/mcp
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth	none
MCP_SESSION_MODE	HTTP 会话模式：auto、stateful 或 stateless。src/index.ts 声明为 stateless；仅在需要覆盖时设置此项。	stateless
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）	info
CATALOG_URL	远程 fleet.json 端点（包含预生成嵌入向量的 schema v2）。必须是绝对 URL。可覆盖此项以接入你自己的 fleet。	https://caseyjhand.com/fleet.json
CATALOG_FETCH_TIMEOUT_MS	获取 fleet.json 时每个请求的超时时间：整数毫秒，范围为 1–2147483647。	10000
CATALOG_REFRESH_SECONDS	后台轮询刷新 fleet.json 的间隔。0 表示禁用；正值最高为 2147483.647 秒，并使用运行时的毫秒计时器精度。	3600
EMBEDDING_MODEL_ID	用于查询嵌入的 Hugging Face 模型 ID。必须与 fleet.json.embeddingModel 匹配。	Snowflake/snowflake-arctic-embed-m-v1.5
SIMILARITY_FLOOR	cyanheads_search_catalog 结果的余弦相似度阈值。必须在 [0, 1] 范围内。	0.3
OTEL_ENABLED	启用 OpenTelemetry	false
OTEL_EXPORTER_OTLP_ENDPOINT	用于链路追踪和指标的 OTLP 基础 URL	未设置
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	显式设置的 OTLP 日志 URL；需要默认 Docker 构建中包含的 OTel 日志对等依赖	未设置
LOG_TOOL_FAILURE_PAYLOADS	记录失败的参数和结果，并按键名脱敏。自由格式值中的机密不会脱敏。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	每条失败日志载荷的 UTF-8 字节上限	16384

完整的可选覆盖项列表请参见 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, runs MCP and packaging linters
  bun run test      # Runs the test suite
  

Docker

docker build -t cyanheads-mcp-server .
docker run --rm -p 3010:3010 cyanheads-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/cyanheads-mcp-server。默认会安装 OpenTelemetry 对等依赖——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/mcp-server/tools	工具定义（*.tool.ts）。包含两个工具——cyanheads_search_catalog 和 cyanheads_describe_entry。
src/services/catalog	Catalog 服务——远程 fleet.json 提供程序，支持原子交换刷新、向量索引、摘要构建器、自描述回退记录，以及查询时的嵌入运行时（@huggingface/transformers，通过可注入接口支持确定性测试）。
src/config	使用 Zod 对服务专属环境变量进行解析和验证。
tests/	单元测试和集成测试，结构与 src/ 对应。
docs/	设计文档和 schema 参考。

开发指南

开发指南和架构规则请参见 CLAUDE.md。简而言之：

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 src/index.ts 中，将新工具注册到传递给 createApp() 的 tools 数组
• 包装外部数据：验证原始数据 → 规范化为领域类型 → 返回输出 schema；切勿伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参见 LICENSE。