datamuse-mcp-server

---

概览

由 Datamuse API 提供支持，为写作、编辑、谜题和命名查找词语。查找符合特定含义的押韵词，探索词汇替代选项，或组合含义、读音、拼写和关联条件进行搜索。

工具

工具	描述
datamuse_find_rhymes	查找完全或近似押韵词，可按含义和拼写筛选
datamuse_find_synonyms	查找同义词、反义词、更宽泛的类别或更具体的类别
datamuse_find_words	组合含义、读音、拼写和指定词汇关系进行搜索，并支持上下文和主题提示
datamuse_list_reference	阅读有关关系、元数据、组合方式和服务限制的离线指南
datamuse_get_word_info	查询所提供拼写的原始元数据，并返回带索引的部分结果

功能参考

datamuse_find_rhymes _工具

• 必填参数 word；rhyme_type 为 exact（默认）或 near，不会混合；可选的 means_like 和 spelled_like 可缩小同一搜索范围。仅支持英语
• 通用搜索选项：limit（默认值为 20）、offset（默认值为 0）、include_definitions、include_pronunciation 和 include_ipa（元数据选项默认值为 false）。结果行包含 Datamuse 提供的所有元数据

---

datamuse_find_synonyms _工具

• 必填参数 word；relation 为 synonyms（默认）、antonyms、broader（直接上位词）或 narrower（直接下位词）。仅支持英语
• 与押韵搜索使用相同的通用搜索选项；统计关联词属于 datamuse_find_words 的 associated 关系

---

datamuse_find_words _工具

• 至少提供 means_like、sounds_like、spelled_like（上游拼写模式）之一，或最多 14 个 relations: [{ relation, word }]；所有条件均需同时满足，重复的关系会保留。left_context、right_context 和最多五个 topics（每个为单个单词）只影响排序
• 关系包括：exact_rhyme、near_rhyme、synonyms、antonyms、broader、narrower、parts、wholes、nouns_modified_by、adjectives_describing、followers、predecessors、associated、homophones、consonant_match；datamuse_list_reference 会说明它们的方向
• vocabulary 为 en（默认值）或 es；西班牙语支持含义、发音和拼写约束，不支持关系。拒绝原因类型包括：missing_constraint、unsupported_vocabulary_relation、invalid_context_hint

Datamuse 使用支持的 OneLook 语法解析拼写模式：

模式	含义
*、?	任意长度，或一个字符
//listen	字谜，包括 lets in 等词组
c@t、s#@p	@ 匹配一个英语元音（包括 y）；# 匹配一个辅音
*+abc	将字母限制为 a、b、c；允许重复和空格
b????-e	五个字符的模式，排除 e
hipopatamus	查找拼写相似的词，不使用通配符语法

对于字谜，使用 {"spelled_like":"//listen"} 调用 datamuse_find_words。+letters 限制允许使用的字母，-letters 排除这些字母；两者都不要求必须包含列出的每个字母。

---

datamuse_get_word_info _工具

提供 1–100 个非空白 words，每个不超过 200 个字符。前十个会在共享请求预算内按顺序处理；后续条目返回 processing_cap。所有请求、重试和间隔等待共用一个 20 秒的截止时间。已完成的结果不受单个条目失败影响；仍在等待处理的条目返回 deadline_exceeded。调用方取消操作会停止本次调用。

相同的 include_definitions、include_pronunciation 和 include_ipa 选项均适用。每个带索引的结果都包含经修剪的调用方 input，以及完整的原始 row、包含恢复方法的失败原因，或未处理原因。只接受带 query 标签且在 Unicode 小写转换后与所提供拼写匹配的回显：Ice Cream 可以返回原始 row.word='ice cream'，但不会替换为纠正后的拼写。缺失的元数据仍保持缺失，重复项会保留各自的索引。在两个 MCP 接口上，查询输出均为完整内容，且不会按字节切片。

datamuse_list_reference _工具

• topic 可为 all（默认值）、relations、metadata、combinations 或 limitations
• 返回静态的 sections: [{ topic, text }]，不发起网络请求

功能

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

Datamuse 专属功能：

• 实时查询 Datamuse 固定的 HTTPS /words 端点，不使用本地镜像或存储查询记录
• 所有工具和租户共享一个请求预算：每秒最多启动一次请求、同一时间最多有一个请求在途、使用有界队列，并重试一次。此预算仅在进程内生效，因此不会计入其他进程或使用相同出口地址的其他用户
• 结果是从语料库中提取的建议，包含依赖词义、有时为猜测的元数据（词性、音节数、每百万词频率 f:）。这些结果并不能证明词典的完整性或是否适合诗歌创作

便于 Agent 使用的输出：

• 回显实际查询并如实报告上限：每次搜索都会返回 effectiveQuery、returnedCount、limitReached 和 truncated，以及相关提示和 nextOffset。超过 1000 的正安全整数限制会被截到 1000，并回显 requestedLimit 和实际生效的 limit。无效整数会在执行 I/O 前被拒绝
• 按完整行导航：offset 接受 0–999。搜索会获取 max=min(1000, offset+limit) 条结果，并在每个序列化 MCP 表面不超过 64,000 字节的前提下选择完整行，其中包括转义和补充信息。本地字节数上限会令 truncated=true；若提供了 nextOffset，请使用 offset=nextOffset 重新运行。若单行过大，则会完整返回，并附带软性预算提示，同时推进 offset。API 上限提示与字节数截断相互独立。不同调用间的排名可能变化，因此 offset 仅用于尽力导航，可能出现重复或遗漏；它们不是快照、稳定分页、结果总数或已无更多结果的证明。无法继续浏览索引 999 之后的结果
• 短语关系恢复：短语目标仍会被接受且保持不变。当关系查询无结果时，提示会说明短语覆盖有限，并建议使用 means_like 或 sounds_like；押韵提示还会建议明确尝试最后一个词
• 可选发音：include_pronunciation 会在 md 后追加 r；include_ipa 会隐含启用发音并添加 ipa=1。可能同时出现原始 pron: 和 ipa_pron: 标签。ARPAbet 重音数字表示：0 为无重音，1 为主重音，2 为次重音；发音可能是猜测的、依赖词义的，也可能缺失
• 无损行：word 以及 Datamuse 发送的 score、numSyllables、tags、defs、defHeadword 等其他字段均保持不变，并遵循上游顺序；structuredContent 与围栏 JSON 文本中的内容完全相同。score 仅用于对单次查询的结果进行排序
• 类型化错误：针对访问错误、速率限制（upstream_rate_limited 和 pacer_shed，附带 retryAfter）、格式错误的上游数据以及无效输入，声明相应原因，并提供恢复提示

访问、隐私与署名

Datamuse 当前说明，无需密钥时每天最多可访问 100,000 次，并要求面向客户的应用联系他们。Datamuse 宣布将于 2027 年初开始手动发放 API 密钥，但公布的日期互相矛盾：使用说明中为 1 月 1 日，横幅中为 2 月 1 日。目前尚未公布密钥格式，因此本服务使用无需密钥的 API，切换时访问可能中断。

查询会发送给 Datamuse，后者会临时保留查询日志，直至次日结束。服务负载日志记录和遥测均为可选功能；发送敏感文本前，请检查相关设置。

词语结果和词汇元数据来自 Datamuse；有关数据来源和署名要求，请参阅其文档。Apache-2.0 许可证仅适用于本服务的代码，不适用于上游数据。

入门

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

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

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

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

也可以使用 Docker：

{
  "mcpServers": {
    "datamuse-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/datamuse-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+）。
• 当前无需 Datamuse 凭据；有关已公布的密钥过渡，请参阅访问、隐私与归属。

安装

1. 克隆仓库：

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

2. 进入目录：

cd datamuse-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env for transport, authentication, logging, or telemetry overrides

配置

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_HOST	HTTP 绑定地址。	127.0.0.1
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

有关所有服务端设置和常见框架覆盖项，请参阅 .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, and more
  bun run test      # Runs the test suite
  

项目结构

目录	用途
src/mcp-server/tools/definitions	五个工具定义和共享的搜索增强功能。
src/services/datamuse	固定端点客户端、共享请求节流、上游架构和 JSON 渲染。
tests/	服务、工具和序列化测试。
docs/	界面设计和生成的目录树。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要概述：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 src/index.ts 的 createApp() 数组中注册新工具和资源
• 封装外部 API 调用：校验原始数据 → 规范化为领域类型 → 返回输出架构；绝不捏造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。