dict

azerbaijan-mcp-dict

仅限本地的 MCP 服务，用于查询阿塞拜疆语释义词典《Azərbaycan dilinin izahlı lüğəti》（4 卷，约 45,000 个词条）。它可以查词、按释义查找词条，并按印刷顺序浏览词典，同时显示每个词条所在的卷、页和栏。

首次使用时，服务会从本项目的发布页下载一次词典数据库（5.6 MB），并将其与基于数据库构建的搜索索引一同保存在缓存文件夹中。该词典是受版权保护的印刷作品，本项目没有获得其使用许可：请阅读下方的数据来源与条款。设置 DICT_DB 可改用你自己的数据库。服务在你的计算机上运行，绝不会作为托管服务提供。

工具

工具	功能
define(word, max_chars?)	按印刷顺序列出词头对应的词条，包括释义、词源注释（origin）、卷册位置，以及 bax 指针指向的词头。同形词会作为独立词条列出（ÇAY¹、ÇAY²）。词条会按 max_chars 截断（默认 3,000，最高 50,000）。若未找到，则会列出可尝试的词头。
search(query, exact?, limit?, offset?)	查找文本包含所有查询词的词条，并优先显示查询内容拼出的词头。可按释义查找词语，例如 su qabı。limit 范围为 1–50（默认 10），可用 next_offset 翻页。
browse(word?, entry_id?, before?, after?)	按印刷顺序浏览某个词头附近的词条，如同翻阅纸质词典：before 和 after 的范围均为 0–50（默认分别为 3 和 7）。可通过 next_id 和 previous_id 从任一端继续浏览。
read_entry(entry_id, offset?, max_chars?)	从指定字符偏移量处读取词条，以查看 define 或 search 截断的内容。有些词条长达数万字符。

例如，若想问“表示盛水容器的词是什么？”，可先调用 search("su qabı")，再对找到的词头调用 define。若想问“词典中 kitab 后面是什么？”，则可调用 browse("kitab")。

值得注意的事项：

• 基本词形。 词典列出的是词条，而不是变形形式：查 kitab，而不是 kitabları。 因此，define 会返回 match: none，并附上 suggestions（词干、以该词开头的词条、相近词）和说明。
• define 可以容错的内容。 可按印刷形式输入词条（AB(B)ASI、ÇAY²、AB-HAVA, ABÜHAVA），也可使用指向该词条的编号（çay2）；其他破折号、弯引号和不可见字符也可以容错。大小写方面：I 和 İ 是不同的字母，并会按阿塞拜疆语规则转换为小写。如果没有词条以输入形式拼写，则重音符号和连字符可以容错：seher 可找到 şəhər 和 səhər（match: accent_free）；空格可代替连字符（ata baba）。每种拼写都能找到相应变体：AB(B)ASI 可作为 abası 和 abbası 找到，AB-HAVA,ABÜHAVA 可作为两个词找到。精确拼写优先于去掉重音符号后的同一词（el 和 əl 是不同的词）。
• bax 指针。 仅写有 bax X（参见 X）的词条会在 followed 中附带 X 的词条，最多跟进两步。词条中的其他指针会列在 see 中，并附上它们指向的词条。指向编号义项的指针（bax dərd 3-cü mənada）会指向词条：阅读其文本以了解该义项。
• 搜索。 搜索词必须全部出现在词条中；不支持 OR 等运算符，且最多使用 12 个词。阿塞拜疆语会添加词尾，因此长度为 4 个字母或更长的词会按前 5 个字母匹配（içmək 可找到 içir 和 içən）；exact=true 则匹配完整单词。此处的重音符号必须正确，与 define 不同。
• 引文。 每个词条都有 volume、pdf_page 和 column。页码是卷册 PDF 中的页码，可能与印刷页码不同。
• 文本是从 PDF 文本层机器提取的，可能包含错误。各行会合并；行尾的连字符会被删除，但以下情况除外：词典中带连字符的复合词比不带连字符的形式更常见（ata-baba）；叠词（aşkar-aşkar）；带词尾的数字（1931-ci）；或以 qeyri- 开头的词。只出现一次且在连字符处换行的复合词会丢失连字符。PDF 中以字母间隔排印的斜体 b a x 会识别为 bax。引用时请以印刷版词典为准，而不是本服务。
• 词源。 origin 是词性后方方括号内的注释（ər., fars., fr, əsli lat.）；约有 11,000 个词条包含此信息。
• 首次调用会下载数据库并建立索引，需要几秒钟：整部词典约需 10 秒，索引占用 30 MB。两者都会保存在缓存文件夹中（Windows：%LOCALAPPDATA%\azerbaijan-mcp\dict；macOS：~/Library/Caches/azerbaijan-mcp/dict；其他系统：~/.cache/azerbaijan-mcp/dict），并在数据库文件更改前重复使用。每个数据库都有自己的索引文件，因此多个数据库可以共用此文件夹。指定的数据库会以只读方式打开，绝不会被写入。缓存可随时删除：下次调用时会重新获取数据库并建立索引。如果文件在复制到目标位置时因进程被终止而截断，系统会检测到并重新获取或建立索引。
• 不涵盖的内容： 变形形式（不含形态分析），以及词典的其他版本和同系列词典。

安装

添加到 MCP 客户端配置中（需要 uv）：

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

在 Claude Code 中：claude mcp add dict -- uvx azerbaijan-mcp-dict。

三个可选设置放在客户端的 env 中：

变量	默认值	含义
DICT_DB	无	自有词典数据库的路径。此时不会下载已发布的数据库。
DICT_DATA_URL	此仓库的发布页面	已发布数据库的镜像，仅支持 https（本机可使用 http）。仍会检查其 SHA-256。
DICT_CACHE_DIR	上方的缓存文件夹	存放数据库和索引的位置。系统拒绝重命名操作的文件夹也可使用，例如在 Windows 上由 Claude 桌面应用启动的服务可使用 %LOCALAPPDATA%（WinError 17）：文件会被复制到目标位置。

数据库

已发布的数据库是发布版本 dict-data-1 中的文件 dict-1.sqlite.gz：包含 45,353 个 条目，大小为 5,657,352 字节，SHA-256 为 44515ffca32d7cefc9f659bbe1ecefa82dc6908f17b5d434daffd1f921162022，软件包会固定此值，因此不会使用与之不符的文件。python -m azerbaijan_mcp_dict.asset source.sqlite out.sqlite.gz 会以这种方式打包数据库，并打印需要固定的数值。

自有数据库需要包含一个名为 entries 的表，服务只会读取下方列出的列。metadata 表为可选项。

CREATE TABLE entries (
    id INTEGER PRIMARY KEY,        -- print order
    volume INTEGER NOT NULL,       -- 1 to 4
    headword TEXT NOT NULL,        -- as printed: ÇAY, AB(B)ASI, AB-HAVA,ABÜHAVA
    homonym_index INTEGER,         -- 1, 2, ... for homonyms, else NULL
    entry_text TEXT NOT NULL,      -- what follows the headword, lines as the PDF breaks them
    start_page INTEGER NOT NULL,   -- PDF page of the volume the entry starts on
    end_page INTEGER NOT NULL,
    start_column INTEGER NOT NULL  -- 1 or 2
);
CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL);

会用到的 metadata 键包括：database_title，用于在每个回答中标明来源；以及 entry_count，会与表中的条目数进行核对，以拒绝被截断的文件。其他列和表都会被忽略。制作已发布数据库所用的数据库自身带有全文索引；服务不会使用该索引，因为它会漏掉每个以大写 İ 开头的句首单词（搜索 iki 会找到包含该词的 1,656 个条目中的 1,324 个）。从 PDF 重建数据库的脚本已在 MCP-31 中跟踪。

数据源与条款

服务器唯一发出的请求是从 github.com 下载一次数据库，每个缓存文件夹各下载一次。根据仓库的数据政策，截至 2026-11-03 的核查结果如下：

• 出版方： 书目资料将该词典列为由 Şərq-Qərb 于 2006 年在巴库出版（由 Ə. Orucov 等人编纂，A. Axundov 主编）。未找到官方在线版本；azleks.az 提供电子版，但须注册，相关条款不明确；非官方扫描件也在流传。
• 条款与许可： 未找到相关信息，因此该文本按保留所有权利处理。项目所有者于 2026-11-03 决定仍将提取出的数据库作为本仓库的发布资源发布，未征求出版方许可。这偏离了数据政策中条款优先的原则，也带来了被投诉的风险。该文本仅存在于发布资源中，不会放入软件包、仓库或测试中。如果出版方、作者或其继承人提出异议，将立即删除该资源。
• robots.txt、速率限制与缓存： 不适用于发布文件。下载时会发送 User-Agent azerbaijan-mcp-dict/<version> (+<repository URL>)，只发出一次请求；遇到网络错误或服务器错误时重试一次；遇到 HTTP 403 和 429 时停止；拒绝超过 100 MB 的文件，并且不会使用 SHA-256 与固定值不符的文件。文件会永久保留在缓存文件夹中。测试运行时会阻止外部网络访问。
• 署名： 每个回答都包含 source（数据库标题）和 attribution，说明该文本是非官方的机器提取结果；每个条目都标明卷号、PDF 页码和栏号。
• 个人数据： 无。条目引用已出版文献，并像词典一样注明作者姓名；不会返回或存储任何有关私人个人的信息。
• 是否联系出版方： 否（MCP-32）。
• 决定： 继续，仅使用本地 stdio，并将数据库作为发布资源发布（MCP-34）。

tests/ 会按照真实词典的布局构建一本虚构词典；本仓库中没有真实词典的任何一行内容。要使用你自己的数据库运行契约测试，并检查已发布的数据库：

DICT_DB=/path/to/azerbaycan_lugeti_1-4.sqlite uv run pytest -m live packages/dict

非官方项目，与出版方或编纂该词典的研究所无关联，也未获其认可。