glossary-mcp

A small, general-purpose MCP server that lets an AI read, search, and safely edit a glossary file in the conlangkit glossary format — for any glossary, not tied to any one project.

The glossary is a Markdown pipe-table with four columns:

lemma | tags | definition | notes
----- | ---- | ---------- | -----
core  | tier | the constitutive tier-1 material of a party | never shared

Writes go through conlangkit, which owns the file: it keeps entries sorted (by byte order) and re-emits the glossary on save. On an already-sorted file that yields a minimal diff — only the touched row moves. The file is re-read from disk before each write (so a long-lived server picks up external hand-edits) and the write is atomic (temp file + os.replace).

Prerequisites

• Python 3.11+
• uv
• A glossary directory or file, pointed to by GLOSSARY_PATH

conlangkit (the glossary format library) is a normal PyPI dependency, pulled in by uv sync.

MCP SDK compatibility

0.1.0 declared only mcp>=1.0, so once mcp 2.0 was released a fresh resolve pulled it in — and 2.0 removed mcp.server.fastmcp. The server then died at import with ModuleNotFoundError, which a client sees only as a server offering no tools at all (a crashed stdio server cannot report why). If you are pinned to 0.1.0, upgrade — restarting will not help. 0.1.1 pinned mcp<2 as a stopgap; 0.2.0 ports to the 2.x API proper.

Installation

uv sync   # creates .venv, installs glossary-mcp (editable) + conlangkit + dev deps

Running tests

uv run pytest   # runs the suite with branch coverage (gate: 100%)

The smoke tests run without GLOSSARY_PATH. Integration tests run against a fixture glossary.

Running the server

export GLOSSARY_PATH=/path/to/glossary        # a directory containing glossary.md …
export GLOSSARY_PATH=/path/to/glossary.md     # … or a direct path to the file
uv run glossary-mcp

GLOSSARY_PATH may be a directory (the server looks for glossary.md inside it) or a file. The server uses stdio transport. For a local checkout, set command to a resolvable path, e.g. the project's /path/to/glossary-mcp/.venv/bin/glossary-mcp:

{
  "mcpServers": {
    "glossary": {
      "command": "glossary-mcp",
      "env": {
        "GLOSSARY_PATH": "/path/to/glossary"
      }
    }
  }
}

For consuming the published package from another repo without a local checkout or absolute paths, use uvx — see the next section.

Consuming from another repo (portable .mcp.json)

glossary-mcp is published to PyPI, so any other repo can wire it into its MCP configuration with no local checkout, no venv, and no absolute paths. uvx fetches and caches the package (and its conlangkit / mcp dependencies) on demand:

{
  "mcpServers": {
    "glossary": {
      "type": "stdio",
      "command": "uvx",
      "args": ["glossary-mcp==0.2.0"],
      "env": {
        "GLOSSARY_PATH": "${CLAUDE_PROJECT_DIR:-.}/../glossary"
      }
    }
  }
}

• command: "uvx", args: ["glossary-mcp"] — the console-script name equals the package name, so no --from flag is needed. uvx resolves the package from PyPI into an ephemeral, cached environment on first launch.
• GLOSSARY_PATH is the only required environment variable. It may point at a directory (the server looks for glossary.md inside) or directly at a file. The ${CLAUDE_PROJECT_DIR:-.}/../glossary value assumes the standard sibling layout where the consuming repo and its glossary repo are checked out side by side. ${CLAUDE_PROJECT_DIR} resolves the project root and requires Claude Code ≥ v2.1.195; the :-. fallback keeps it working (relative to the current directory) on older versions and other MCP clients.
• Pin the version while pre-1.0. Because the tool surface may still change before 1.0, pin so a new release can't reach every consuming repo at once and break them in lockstep: "args": ["glossary-mcp==0.2.0"]. Bump deliberately (repo by repo, or via your propagation tooling). Float the version (bare "glossary-mcp", always latest) only once the surface stabilizes at ≥ 1.0.

Tools

A note on slashes in definitions

In the conlangkit format, / separates alternative senses in the definition column. A definition that contains a literal slash (e.g. allow/ask/deny) is stored escaped on disk as allow\/ask\/deny — which renders as a plain / on GitHub (CommonMark/GFM). You never type the escape: pass ordinary prose (with plain slashes) to add_term/update_term, and read ordinary prose back — the server escapes and unescapes transparently.

Case sensitivity

Lemma lookup, insertion, and sorting are case-sensitive (byte order) — conlangkit targets writing systems where case-folding is not meaningful, so core and Core are distinct entries. Use each term's canonical case: lowercase for ordinary terms, uppercase for acronyms (AID, GCD). This keeps you from creating near-duplicates.

Methodology

Non-trivial work in this repo runs under the cc craft methodology (~/code/me/cc); read constitution.md first. Follow strict TDD (see AGENTS.md).