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.
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.
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
Node 22.13 or later. The server uses the built-in node:sqlite module, so
npm install never compiles native code.
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.
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"]
}
}
}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.
The server resolves the path in this order:
The --db <path> argument in the args array
GLOSSARY_DB_PATH in the env block
The per-user data directory, the global glossary:
macOS: ~/Library/Application Support/domain-glossary-nodejs/glossary.db
Linux: $XDG_DATA_HOME/domain-glossary-nodejs/glossary.db or
~/.local/share/domain-glossary-nodejs/glossary.db
Windows: %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 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.
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.
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: true when the age reaches the threshold, false otherwise.
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.
Variable | Default | Purpose |
| per-user data directory | path of the SQLite file, below |
|
| staleness threshold in days, below |
|
|
|
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.
The skills/ folder holds 2 skills for coding agents:
domain-glossary-mcp explains how to connect the server and use the tools
domain-glossary-mcp-dev explains the conventions of this codebase
Copy the folder you need into <repo>/.kiro/skills/ or ~/.kiro/skills/. See
skills/README.md.
npm install
npm run build
npm testsqlite3 "$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;"Lists the domain terms that have no definition yet. These gaps come from earlier lookup_term calls. Pass a project to narrow the list.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Name of the project or repository that owns the term, for example production-data-pipeline. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare the tool read-only and idempotent. The description adds meaningful behavior beyond that: missing terms originate from prior lookup_term calls, and the project parameter narrows the result set. This gives the agent useful operational context without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver the core function, the origin of the data, and the optional filtering behavior. Every sentence earns its place, and the most important fact is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one optional parameter, the description fully covers what the tool does, where its data comes from, and how to narrow results. No output schema is present, but the result type is clear from the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter's name and example are already documented. The description adds value by stating that passing a project narrows the list, clarifying the parameter's effect rather than just its identity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is precise: it lists domain terms lacking definitions, which clearly distinguishes it from sibling tools lookup_term and save_term. The phrase 'no definition yet' communicates exactly the intended resource and state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that the listed gaps come from earlier lookup_term calls, which contextualizes when this tool is useful. It also tells the agent that passing a project narrows the list, offering clear usage guidance. However, it does not explicitly state when to prefer lookup_term or save_term instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Name of the domain term. Use aggregate roots and entities, for example Order or Shipment. Do not use DTOs, requests, responses, mappers or internal value objects. | |
| project | Yes | Name of the project or repository that owns the term, for example production-data-pipeline. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
This is a strong disclosure of behavior beyond the annotations. It reveals that when a term has no definition, the server records the gap and reports the term as undocumented. This explains the readOnlyHint:false annotation even though the primary action is a lookup. It also states the output length as 2 to 3 lines, which is useful and not visible elsewhere.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three tight sentences with no filler. The core purpose is front-loaded, the alternative context is given next, and the behavioral caveat is last. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter lookup tool with no output schema, this description is complete: it states what is returned, the output length, when to use it, and the side-effect behavior for undocumented terms. The annotations provide idempotency, and the description explains the non-read-only aspect. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters with 100% coverage, so the baseline is 3. The description reinforces the concept of 'domain term' and 'aggregate root or entity', but adds little beyond what the parameter descriptions already state. It does not clarify project semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific verb and resource: 'Returns the business definition of a domain term in a project'. It is easy to tell this is a read/lookup operation. It does not explicitly contrast itself with the sibling tools save_term and list_missing_terms, so it falls just short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: use it when you need the meaning of an aggregate root or entity, and call it instead of reading javadoc or a README. It does not explicitly mention when to prefer save_term or list_missing_terms, but it clearly scopes the intended use case and even warns against using DTOs or internal value objects via the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Name of the domain term. Use aggregate roots and entities, for example Order or Shipment. Do not use DTOs, requests, responses, mappers or internal value objects. | |
| project | Yes | Name of the project or repository that owns the term, for example production-data-pipeline. | |
| description | Yes | Business definition of the term, 2 to 3 lines. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate that this is a write operation (readOnlyHint=false) and idempotent (idempotentHint=true). The description adds useful content guidance about keeping text to 2-3 lines and describing business meaning, but it does not disclose additional behavioral traits such as authentication needs or side effects beyond 'replaces.' No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the action and resource, then gives a concise, actionable instruction about how to write the definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter write tool with full schema coverage and annotations, the description plus schema is sufficient for an agent to call it correctly. The only notable gap is explicit routing guidance against sibling tools, but that is not essential for successful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for all three parameters, so the schema already documents their meaning. The description repeats the 2-3 line constraint already present in the description parameter's schema and does not add new parameter-level semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action 'Stores or replaces' and the resource 'business definition of a domain term in a project.' This clearly distinguishes it from the read-oriented sibling tools lookup_term and list_missing_terms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for creating or updating term definitions, but it does not explicitly mention when to prefer it over lookup_term or list_missing_terms. The sibling names make the contrast inferable, but no explicit guidance or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0list_missing_termslookup_termsave_termScored 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.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Versioned documentation registry and semantic search for AI tools and coding assistants.
A shared team wiki your coding agents read and write — across every repo and every MCP client.
Shared knowledge base for AI agents. Semantic search across agents, no setup required — just a URL.
