domain-glossary-mcp
This server lets coding agents get and maintain short business definitions of domain terms from a shared SQLite glossary.
Look up a term's definition with
lookup_term, including age, staleness, and source.Save or replace a definition with
save_term, optionally recording a reference.Mark a definition as current with
refresh_term.List undocumented terms with
list_missing_terms, optionally filtered by project.Automatically record gaps when a term has no definition yet.
Detect stale definitions after a configurable threshold and warn the agent.
Share one central glossary across projects, stored in SQLite.
Configure the database path, staleness threshold, and log level via CLI flags or environment variables.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@domain-glossary-mcp What is the business definition of 'Customer' for project Acme?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
domain-glossary-mcp
MCP server that serves the business definition of a domain term on demand. The coding agent asks for one term and receives 2 or 3 lines, instead of loading a javadoc or a README into the context window.
The data lives in one central SQLite file shared by every project. Each entry has a project, a term, a description, an optional reference to the source and the time of the last update.
How the gap tracking works
When the agent asks for a term that has no definition, the server creates the
entry with description = NULL and reports the term as undocumented. The gap
stays recorded, so list_missing_terms shows what the team still needs to
write.
Related MCP server: MCP Documentation Server
Requirements
Node 22.13 or later. The server uses the built-in node:sqlite module, so
npm install never compiles native code.
Install
From a private registry:
npm install domain-glossary-mcpFrom a git repository:
npm install git+ssh://git@your-host/your-org/domain-glossary-mcp.gitThe package exposes the domain-glossary-mcp binary.
Register in an MCP client
Add an entry to the client config, for example .mcp.json in the target
repository. For Kiro, use .kiro/settings/mcp.json with the same shape.
Only command and args are required. Every parameter below is optional and
has a default, so the shortest config runs the server against the global
glossary:
{
"mcpServers": {
"domain-glossary": {
"command": "npx",
"args": ["-y", "domain-glossary-mcp"]
}
}
}This full config sets every parameter. Use it as a template, then remove the lines you do not need:
{
"mcpServers": {
"domain-glossary": {
"command": "npx",
"args": [
"-y",
"domain-glossary-mcp",
"--db", "/absolute/path/to/glossary.db",
"--stale-days", "180"
],
"env": {
"GLOSSARY_DB_PATH": "/absolute/path/to/glossary.db",
"GLOSSARY_STALE_DAYS": "180",
"GLOSSARY_LOG_LEVEL": "info"
},
"disabled": false,
"autoApprove": ["lookup_term", "list_missing_terms"]
}
}
}Parameters
Parameter | Required | Default | Purpose |
| yes | — | the runner, for example |
| yes | — | the package name plus the flags below |
| no | per-user data directory | path of the SQLite file |
| no |
| age in days before |
| no | per-user data directory | path of the SQLite file, below |
| no |
| staleness threshold, below |
| no |
|
|
| no |
| turns the server off without removing the entry |
| no |
| tool names the client runs without a prompt |
A flag wins over the matching environment variable. Set the path or the
threshold once, in the args or in the env, not in both.
Keep save_term and refresh_term out of autoApprove. A write to a shared
glossary deserves one confirmation.
Leave out --db to use the global glossary in the per-user data directory.
Database location
The server resolves the path in this order:
The
--db <path>argument in theargsarrayGLOSSARY_DB_PATHin theenvblockThe per-user data directory, the global glossary:
macOS:
~/Library/Application Support/domain-glossary-nodejs/glossary.dbLinux:
$XDG_DATA_HOME/domain-glossary-nodejs/glossary.dbor~/.local/share/domain-glossary-nodejs/glossary.dbWindows:
%LOCALAPPDATA%\domain-glossary-nodejs\Data\glossary.db
The server creates the directory when it is absent and enables WAL mode. Never
point the path inside node_modules, because npm deletes that content on each
reinstall.
The --db-path spelling works as an alias of --db, and --db=<path> in one
token works too. A leading ~ becomes the home directory, and a relative path
becomes absolute against the working directory. A JSON config cannot rely on
shell expansion, so the server does it.
The startup log line reports the chosen path and its origin:
{"level":"info","message":"domain-glossary MCP server ready","dbPath":"/tmp/team/glossary.db","dbPathSource":"argument","staleAfterDays":180,"staleAfterDaysSource":"default"}The value of dbPathSource is argument, environment or default. The
staleAfterDays field reports the threshold, and staleAfterDaysSource
reports its origin with the same 3 values.
WAL files and version control
WAL mode is active. While the server runs, a glossary.db-wal and a
glossary.db-shm file sit next to glossary.db. The server checkpoints the
WAL after every write, so glossary.db holds each new row at once. A separate
reader, such as a git commit, sees the row without a wait; there is no need
to disconnect the server or run a manual PRAGMA wal_checkpoint. A clean
shutdown also empties the side files, so only glossary.db remains. A crash
may leave the side files in place; the next start reads the data from them, so
no data is lost.
Do not commit any of the 3 files when the path sits inside a repository. The
-wal and the -shm files are transient. The .db file is a live database,
and a commit of it causes merge conflicts and races between writers. Add these
lines to the .gitignore of the consuming repository:
*.db
*.db-wal
*.db-shmThe simplest way to avoid this is to keep the database out of the repository:
leave --db unset to use the per-user data directory, or point it at a path
outside the working tree.
Tools
Tool | Input | Result |
|
| the definition, its age and a |
|
| creates or replaces the definition, records the source and sets the update time to now |
|
| moves the update time to now, keeps the text |
|
| the terms that have no definition |
The optional reference on save_term records where a definition came from: a
URL, user when a person gave it, or agent when the model wrote it from the
code. lookup_term reports the source on a later read.
The comparison of project and term ignores letter case. The server keeps
the original spelling of the stored entry.
The server rejects names that end with DTO, Request, Response, Mapper
or Config. The glossary holds aggregate roots and entities, not transport
objects.
Staleness
The server judges whether a definition is old, so the agent does not do the
date math. lookup_term returns 3 extra fields on a documented term:
ageDays: the age of the definition in whole days.stale:truewhen the age reaches the threshold,falseotherwise.staleAfterDays: the threshold in effect.
When stale is true, the text of the result carries a warning that the
definition may be outdated and suggests the next step: confirm with the dev,
then save_term for a change or refresh_term to mark it current.
The threshold is 180 days (about 6 months) by default. Set --stale-days <n>
in the args, or GLOSSARY_STALE_DAYS in the env, to change it. A value
that is not a positive integer falls through to the next source, so a typo
keeps the default.
Environment variables
Variable | Default | Purpose |
| per-user data directory | path of the SQLite file, below |
|
| staleness threshold in days, below |
|
|
|
Command line arguments
Argument | Default | Purpose |
| per-user data directory | path of the SQLite file. Wins over |
| — | alias of |
|
| staleness threshold in days. Wins over |
Logs are JSON lines on stderr. The stdout stream belongs to the MCP transport.
Agent skills
The skills/ folder holds 2 skills for coding agents:
domain-glossary-mcpexplains how to connect the server and use the toolsdomain-glossary-mcp-devexplains the conventions of this codebase
Copy the folder you need into <repo>/.kiro/skills/ or ~/.kiro/skills/. See
skills/README.md.
Development
npm install
npm run build
npm testInspect the database
sqlite3 "$GLOSSARY_DB_PATH" "SELECT project, term, description, reference, updated_at FROM glossary;"
sqlite3 "$GLOSSARY_DB_PATH" "SELECT project, term FROM glossary WHERE description IS NULL;"Available Tools
3 toolslist_missing_termsList undocumented domain termsARead-onlyIdempotent
Lists the domain terms that have no definition yet. These gaps come from earlier lookup_term calls. Pass a project to narrow the list.
Inputs: project.
lookup_termLook up a domain termAIdempotent
Returns the business definition of a domain term in a project, in 2 to 3 lines. Call this instead of reading javadoc or a README when you need the meaning of an aggregate root or entity. When the term has no definition yet, the server records the gap and reports the term as undocumented.
Inputs: term (required), project (required).
save_termSave a domain termAIdempotent
Stores or replaces the business definition of a domain term in a project. Keep the text to 2 or 3 lines and describe the business meaning, not the code structure.
Inputs: term (required), project (required), description (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: looking up a definition, saving or replacing one, and listing missing definitions. There is no meaningful overlap or ambiguity between them.
All tool names follow a consistent lowercase snake_case verb_noun pattern: lookup_term, save_term, list_missing_terms. The naming style is uniform and predictable.
Three tools is well-scoped for a domain glossary server. Each tool covers a necessary core action without redundancy or unnecessary surface area.
The glossary lifecycle is largely covered with lookup, save/replace, and gap identification. A delete_term tool and a way to list all defined terms would make it fully complete, but these are minor gaps that do not block the primary workflow.
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Versioned documentation registry and semantic search for AI tools and coding assistants.
Shared business knowledge, tools and skills for AI agents, with citations and approval controls.
Shared team record of decisions, changes and handoffs that every coding agent reads and writes.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables the management of a technical terminology glossary within an Obsidian vault by providing tools to add, search, and retrieve term definitions. It supports structured Markdown entries featuring both developer-focused and simplified explanations for efficient knowledge management.43-
- AlicenseNot gradedqualityDmaintenanceProvides project documentation, database schema, business rules, and search capabilities as context for Claude Code, enabling more accurate code generation and query writing.ISC
- AlicenseAqualityCmaintenanceEnables coding agents to persist notes, decisions, requirements, and learnings per project in SQLite and retrieve them across sessions via search and status tools.3MIT
- AlicenseNot gradedqualityBmaintenanceGives AI coding agents on-demand retrieval of workspace context, documentation, lessons, decisions and handoffs from a five-level (GLOBAL → WORKSPACE → PROJECT → FEATURE → SESSION) store, so they start with a small rule set instead of re-reading bloated docs. Exposes tools for dependency routing, knowledge search, doc reading and health checks backed by a zero-dependency SQLite + FTS5 memory with cross-project sharing of global-scoped knowledge.MIT