cldf-mcp

cldf-mcp

一个 MCP 服务，让 AI 助手能够基于事实，访问以 CLDF 格式发布的跨语言数据。0.1 版本包含：

• WALS，即《世界语言结构地图集》：涵盖 2,660 种语言的 192 项类型学特征 （语序、音系、形态……），每个数据点均附有来源；
• Glottolog：收录全球约 27,000 个语言种类的目录，以及其 分类、别名、濒危状况和描述状态。

大模型知道 WALS 的存在，却不一定能准确回答具体问题，例如某种语言在特征 85A 上的取值，或有多少语言同时采用 SOV 语序和前置词。此服务会返回实际数据、数据所属的版本，以及相关参考文献。

与查询表有何不同

• 按语系统计。 相关语言会继承特征，因此“400 种语言具有某特征”可能意味着“有三个大语系具有该特征”。每项统计都附有不同语系（来自 Glottolog）和 WALS 属的数量，以及最大语系所占的比例，让模型能够区分跨语言的倾向与单一谱系的特征。也可使用 WALS 的平衡 100 种和 200 种语言样本进行筛选。
• 全程提供来源信息。 每个回答都会注明数据集、版本和引文；数据点还附有参考文献来源及页码。
• 不默默猜测。 bsq 是 WALS 中巴斯克语的代码，也是巴萨语的 ISO 代码，因此此服务会先询问，而不是擅自选择。“无数据”绝不会被报告为“不存在”。
• 固定并验证数据。 数据集从带标签的版本获取，并在加载前通过 SHA-256 校验和验证。

快速开始

需要 Python 3.11+ 和 uv（或 pip）。

Claude Code

claude mcp add cldf -- uvx cldf-mcp

Claude Desktop 及其他使用 mcpServers 配置的客户端：

{
  "mcpServers": {
    "cldf": {
      "command": "uvx",
      "args": ["cldf-mcp"]
    }
  }
}

首次使用时，此服务会下载固定版本的数据（约 40 MB），并在几秒内构建本地 SQLite 数据库（约 35 MB）。如需提前完成这些步骤：

uvx cldf-mcp setup

然后可以提问，例如：

• WALS 中哪些语言采用 SOV 语序，但使用前置词？它们分布在不同语系中吗？
• “VSO 意味着使用前置词”是一种真实的倾向吗？请在 WALS 的 200 种语言样本中检验。
• 列出巴斯克语的语序特征，并附上来源。
• WALS 对南岛语系的覆盖情况如何？哪些分支的数据最多？

工具

工具	功能
list_datasets	已加载的数据集、发布版本、覆盖范围、许可证和引用
find_language	名称（包括别名和拼写错误）、ISO 639-3 代码、Glottocode 或数据集代码 → 按排名列出的候选项，包括语系、宏区以及哪些条目包含数据
search_features	在特征名称、章节和值标签中进行关键词搜索 → 特征 ID 和可能的取值
get_feature	定义、章节、作者和取值分布，按语言、语系和语支计数；可选按宏区、语系／子群或 WALS 样本筛选
get_values	语言 × 特征网格，包含取值、评论、来源和完整引用；无法解析的名称会报告候选项，而不会导致调用失败
language_profile	一种语言的全部信息：Glottolog 身份、谱系、濒危情况、描述状态和所有特征取值
filter_languages	匹配最多 8 个条件（AND，并支持 exclude）的语言，可跨数据集筛选，并提供分母（所有条件均有编码的语言数）和语系计数
crosstab	对两个特征进行交叉制表：每个单元格中的语言、语系、语支和最大语系占比；保留值为 0 的单元格；可选按宏区细分
classification	Glottolog 谱系、子级（及其下有多少个数据集条目）和姐妹语言
get_source	数据点中所引用来源 ID 的完整书目信息

资源：

• cldf://guide/typology-caveats：如何负责任地使用计数（抽样偏差、区域效应、覆盖范围、引用）。服务的指令会引导模型查看此资源。
• cldf://datasets：已加载数据的版本、许可证和引用。

数据准备完成后，所有工具均为只读且可离线使用。

配置

设置	默认值
--data-dir / CLDF_MCP_DATA_DIR	~/.cache/cldf-mcp（Linux）、~/Library/Caches/cldf-mcp（macOS）、%LOCALAPPDATA%\cldf-mcp（Windows）
--config / CLDF_MCP_CONFIG	无：用于添加或覆盖数据集的额外 TOML（实验性功能，见下文）
--transport	stdio；远程使用时，可与 --host / --port 搭配使用 streamable-http

其他命令：cldf-mcp info（数据存放位置及数据是否为最新版本）和 cldf-mcp setup --force（重新构建）。

添加数据集（实验性功能）

语言条目带有 Glottocode 的任何 CLDF StructureDataset 都可以与 WALS 一起加载。特征 工具、语系计数和跨数据集筛选会自动支持此数据集：

# my-datasets.toml
[datasets.mydata]
title = "My typological survey"
role = "features"
version = "v1.0"
base_url = "https://raw.githubusercontent.com/me/mydata/v1.0/cldf/"   # or: local_path = "/path/to/cldf"
metadata = "StructureDataset-metadata.json"
license = "CC-BY-4.0"
citation = "Me. 2026. My typological survey."

[datasets.mydata.files]   # every file the loader needs, with optional sha256 checksums
"StructureDataset-metadata.json" = ""
"languages.csv" = ""
"parameters.csv" = ""
"codes.csv" = ""
"values.csv" = ""

cldf-mcp setup --config my-datasets.toml

数据、许可证和引用

服务代码采用 MIT 许可证。数据不属于此软件包：数据从原始发布版本下载，并采用 CC-BY-4.0 许可证。 如果你发布使用此服务获得的结果，请引用相关数据集（见 DATA_LICENSES.md）：

Dryer, Matthew S. & Haspelmath, Martin (eds.) 2013. The World Atlas of Language Structures Online. Leipzig: Max Planck Institute for Evolutionary Anthropology. https://wals.info （CLDF 发布版本 v2020.6）

Hammarström, Harald & Forkel, Robert & Haspelmath, Martin & Bank, Sebastian. 2026. Glottolog 5.3. Leipzig: Max Planck Institute for Evolutionary Anthropology. https://glottolog.org

这是一个独立项目，与 WALS、Glottolog 或 CLDF 团队均无关联。

局限性

• WALS 反映了截至约 2013 年的文献资料，大多数特征仅针对几百种语言进行了编码。百分比以已编码语言为基数，而非以世界上的所有语言为基数。
• 语系计数遵循 Glottolog 的分类，Glottolog 不承认拟议的宏语系（例如 Altaic）。在 17 种没有 Glottocode 的 WALS 语言中，有 10 种根据 WALS 的语系或语支名称匹配到了 Glottolog 语系；其余 7 种保留 WALS 自己的标签（例如 “Niger-Congo”）。
• Glottolog 的完整参考文献未随包提供；其参考文献以链接形式返回。

路线图

• 0.2：Grambank，首个与 WALS 有重叠的数据集，并支持并排比较相关特征。
• 0.3：PHOIBLE 音系清单和 Lexibank 词表 （get_inventory、get_forms）。

开发

git clone https://github.com/hsouf/cldf-mcp && cd cldf-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest                # offline tests on small fixtures (tests/fixtures)
pytest -m network     # downloads the real pinned releases and checks known WALS counts
ruff check src tests && ruff format --check src tests

有关发布到 PyPI 和 MCP Registry 的说明，请参阅 RELEASING.md。