Skip to main content
Glama

dod-mcp

An MCP server that serves a team's Definition of Done from versioned YAML files, one file per task type, and checks the evidence an agent collected against it, criterion by criterion. It never declares an item done.

Prototype, November 2026, built with Claude Code as co-developer. All data in this repository is fictional.

Problem

The Definition of Done usually lives on a wiki page or in a pull request template. The pipeline checks part of it (build, tests, quality gate); people check the rest from memory in the review. Coding agents make this worse: they deliver more changes in less time, they report "done" when the tests are green, and they cannot see criteria that are written down nowhere they look (documentation, sign-offs, operations).

This server keeps the DoD in the team repository, as a shared base plus one file per task type (software development, documents, customer requests …). Agent and people read the same files. The server checks an item against them and reports, per criterion, a status and the evidence or what is missing. Whether the item is done stays the team's decision.

Related MCP server: Spec Kit Acceptance Gate MCP

What it does

Tool

What it does

get_dod

The DoD for a ticket: pass its ticket type and labels. Every criterion of base and type with its origin and check kind, and for evidence criteria which tool delivers the value and what it must show. Without arguments: the list of task types.

check_dod

The evidence the agent collected (source, tool, arguments, time, raw value, commit) against the DoD: met / not_met / needs_judgment per criterion, findings such as evidence_missing, evidence_stale, evidence_other_ref, and a hint how to get what is missing. No overall status.

lint_acceptance_criteria

Acceptance criteria against the rules of their type: Given/When/Then complete and in order, observable Then steps, vague words, numbers without units, required fields and formats. Every finding with line and column.

diff_dod

What changed between two versions of a type (each with its base) or of the base, every entry with its origin. For DoD reviews and retrospectives.

Resource

Content

dod://types

base, mapping and every task type with version label, validity, errors and recorded versions

dod://type/{type}

one resource per type file: base and type merged, every criterion with origin, file and line

dod://type/{type}/version/{n}

an earlier version, with the base it was first served with

template://{type}

the template for acceptance criteria and the rules the lint applies

rubric://dod/{type}

the judgment criteria with question and standards for plausible and doubtful

Prompt

Does

done_check(item)

determines the type, collects evidence with your other servers, runs check_dod, answers the judgment questions with the rubric and reports per criterion. Writes nothing.

All tools are read-only. The server calls no model and holds no credentials for other systems.

Who decides what

Who

Words

For what

Server

met / not_met / needs_judgment

each criterion, from evidence and rules, reproducible

Model in the client

plausible / doubtful

each judgment criterion, with a quote, by the rubric

Team or a named role

"done"

the item; a role confirms attestation criteria

Each criterion says how it is checked: evidence (a value a tool can fetch, such as the quality gate of this commit), judgment (a question, such as "which acceptance criterion has no test?") or attestation (a role confirms, such as operations for the runbook). The agent fetches evidence through the official servers (SonarQube, Azure DevOps, GitHub, Jira …) and passes it on unchanged; the server checks its form, age, commit and value. The reasoning is in docs/design.md.

Quick start

Requires Node.js 26; Docker for the container.

npm install
npm run build
npm test

Local, over stdio

claude mcp add --transport stdio --scope local dod --env DOD_DIR=/absolute/path/to/your/dod -- node /absolute/path/to/dod-mcp/dist/main.js

Then ask Claude Code "Check DEMO-42 against our Definition of Done", or run the prompt as /mcp__dod__done_check DEMO-42 (Claude Code names MCP prompts /mcp__<server>__<prompt>). Without DOD_DIR the server serves the fictional example in dod/.

In a container, over HTTPS

scripts/dev-cert.sh            # self-signed certificate and a token in local/secrets/ (git-ignored)
docker compose up -d --build   # https://localhost:8443/mcp, the example DoD mounted read-only
claude mcp add --transport http dod https://localhost:8443/mcp --header "Authorization: Bearer $(cat local/secrets/tokens)"

Start Claude Code with NODE_EXTRA_CA_CERTS pointing to local/secrets/cert.pem, so it trusts the certificate. One container serves one team: one DoD folder, one database, one set of tokens.

Your team's DoD

dod/
  base.yaml            # applies to every type
  types.yaml           # ticket type / label → task type
  software-dev.yaml    # one file per task type; the file name is the type
# FICTIONAL EXAMPLE: dod/kundenanfrage.yaml
type: kundenanfrage
version: 3
title: Kundenanfrage
extends: base
criteria:
  - id: FRIST
    text: Die erste Antwort ging innerhalb der vereinbarten Frist raus.
    check: evidence
    source: helpdesk.first_response
    expect: { field: first_response_at, not_after: due_at }
    fetch_with: [helpdesk:get_ticket]
  - id: VOLLSTAENDIG
    text: Die Antwort geht auf jede Frage der Anfrage ein.
    check: judgment
    question: Welche Frage der Anfrage bleibt in der Antwort offen?
  - id: ZUSAGE
    text: Zusagen zu Preis oder Termin sind freigegeben.
    check: attestation
    role: Vertrieb
  • A type may only add to the base. A type file that reuses a base id, uses a key such as remove or override, or lacks extends: base is invalid, with file, line and column. Other types keep working.

  • A new type is a new file. It appears as resources without a restart and without code changes.

  • Every change of content raises version. The server records every version it sees in its database; a changed file with an old version number is invalid (version_not_bumped). The YAML files stay the source of truth and change by pull request.

  • expect has six operators: equals, one_of, min, max, present, not_after; field reads nested values with a dotted path.

  • Acceptance rules come in five kinds: gherkin, observable_then, vague_words, numbers_need_units, fields (lines Name: or headings ## Name).

Check the folder in CI with the same loader:

node dist/cli/validate.js dod     # prints file:line:column code: message; exit 0, 1 or 2

Example (fictional)

check_dod on examples/evidence/software-dev-gaps.json, a story whose quality gate was fetched for another commit, whose test results are 30 hours old, and that no second person has looked at:

Criterion

Origin

Check

Status

Finding

Hint or question

ERGEBNIS-VERLINKT

base

evidence

met

–

FOLGEARBEIT

base

judgment

needs judgment

–

Welche offene Folgearbeit aus dem Ergebnis ist noch nicht als eigenes Item erfasst?

ZWEITE-PERSON

base

attestation

not met

attestation_missing

Ask the role Teammitglied to confirm; the agent does not confirm on its own.

QUALITY-GATE

software-dev

evidence

not met

evidence_other_ref

Fetch with get_project_quality_gate_status for commit 9f2c1ab.

BUILD

software-dev

evidence

met

–

TESTS

software-dev

evidence

not met

evidence_stale

Fetch with get_test_results for commit 9f2c1ab.

TESTAENDERUNG-AUSGEWIESEN

software-dev

evidence

met

–

KRITERIEN-GETESTET

software-dev

judgment

needs judgment

–

Zu welchem Akzeptanzkriterium fehlt ein Test, der genau dieses Verhalten prüft?

RUNBOOK

software-dev

attestation

met

–

4 met, 3 not met, 2 need judgment, about 1,000 tokens of output. lint_acceptance_criteria on examples/acceptance/software-dev.md finds two incomplete scenarios, an unobservable Then ("ist zufrieden"), a number without unit ("in unter 2") and two vague words; the fixed version is clean. The run is in docs/verification.md.

Configuration

Environment variables only.

Variable

Default (stdio / container)

Purpose

DOD_TRANSPORT

stdio / https

transport

DOD_DIR

<repo>/dod / /dod

DoD folder

DOD_DATABASE

sqlite:<repo>/local/dod.sqlite / sqlite:/data/dod.sqlite

version history; sqlite::memory: for tests

DOD_PORT

– / 8443

HTTPS port

DOD_TLS_CERT_FILE, DOD_TLS_KEY_FILE

– / /run/secrets/tls_cert, /run/secrets/tls_key

certificate and key (PEM)

DOD_TOKEN_FILE

– / /run/secrets/dod_tokens

bearer tokens, one per line, at least 32 characters

DOD_ALLOWED_HOSTS

– / localhost,127.0.0.1

accepted Host values

DOD_ALLOWED_ORIGINS

– / empty

accepted Origin values; empty rejects every browser request

Security

  • HTTPS only; no plain-HTTP mode. Host and Origin are checked before the token, the token before anything else. Tokens come from a mounted file, never from an environment variable, and are never logged.

  • The container runs as a non-root user on a read-only file system; only /data is writable. The DoD folder is mounted read-only.

  • No regular expressions from YAML, an alias limit for YAML, size limits for files, evidence and request bodies.

  • The database holds DoD file versions only: no evidence, no acceptance texts, no request data.

  • Evidence comes from the agent. The server checks form, age, commit and value, not authenticity; for criteria where a forged value would be expensive, run the same check in CI (an open point).

Limits

The server cannot tell whether evidence is genuine or who gave a confirmation; word lists miss paraphrases; the number rule relies on German nouns being capitalised; the version history starts with the first sync. expect cannot yet compare two fields with each other or compute deadlines relative to another time. Details: docs/design.md, sections 12 and 16.

How this was built

The starting point was a concept sketch for a team MCP server "Definition of Done" (14 November 2026). I defined the problem and the design rules from my two earlier MCP servers (deterministic findings with a location, judgment in the client model, nothing set to done automatically), approved the design (docs/design.md) and reviewed each of the five phases before the next one started. Claude Code drafted the code, the tests and the documentation.

To test the format against reality, a draft DoD was extracted read-only from one real repository. That draft stays outside this repository; it led to two format changes (nested fields in expect, headings as fields) and to the open points on field comparison and deadlines.

Licence

MIT, see LICENSE.

Available Tools

4 tools
check_dodCheck an item against its Definition of DoneA
Read-onlyIdempotent

Check the evidence you collected for an item against its DoD. For every evidence criterion, fetch the value with the tool named in get_dod and pass it unchanged: criterion, source, tool, arguments, retrieved_at (ISO 8601 with time zone), raw and, for commits, ref. Never invent or retype values; leave out what you could not fetch. Returns met / not_met / needs_judgment per criterion with findings (evidence_missing, evidence_stale, evidence_other_ref …) and a hint on how to get missing evidence. There is no overall status: the team decides whether the item is done. Read-only; writes nothing to the ticket.

Inputs: item (required), as_of, evidence. Returns: item, type, as_of, limits, +6 more

diff_dodCompare two versions of a DoDA
Read-onlyIdempotent

What changed in the Definition of Done of a task type between two versions of its file, each merged with its base, or between two versions of the base (type: "base"). Every added, removed or changed criterion and rule names its origin. Defaults: from the previous recorded version to the DoD in force now. For DoD reviews and retrospectives. Read-only.

Inputs: type (required), to, from. Returns: to, from, type, rules, +4 more

get_dodGet the Definition of DoneA
Read-onlyIdempotent

The Definition of Done for a ticket: pass ticket_type and labels as they are in the ticket (or type explicitly). Returns every criterion of base and type with its origin and check kind: evidence (which source and tool deliver it, what value is expected, how old it may be), judgment (a question you answer with rubric://dod/{type}) or attestation (a role confirms). Without arguments: the list of task types. An ambiguous or unknown type is an error with a hint, never a default. Read-only.

Inputs: type, labels, ticket_type. Returns: dod, overview, resolution

lint_acceptance_criteriaLint acceptance criteriaA
Read-onlyIdempotent

Check acceptance criteria against the rules of their task type: Given/When/Then complete and in order, observable Then steps, vague words, numbers without units, required fields and formats. Pass the text as it is in the ticket plus ticket_type and labels (or type). Every finding has line, column, rule and a hint; template://{type} shows the expected form. Deterministic and read-only; it does not rewrite the text.

Inputs: text (required), type, labels, ticket_type. Returns: type, limits, summary, findings, +4 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool has a distinct verb-purpose: get_dod retrieves criteria, check_dod validates collected evidence, lint_acceptance_criteria validates AC text, diff_dod compares versions. The only mild overlap is get_dod's no-argument mode (listing task types) and its role as the prerequisite for check_dod, but descriptions make the pipeline order explicit.

    Naming Consistency5/5

    All four names follow a clean verb_noun snake_case pattern (get_, check_, lint_, diff_), with the DoD-related tools sharing a consistent _dod suffix. No mixed conventions or casing.

    Tool Count4/5

    Four tools is small but each covers a genuinely different operation in a narrow read-only domain, so nothing feels padded. It is on the thin side — no write/attestation tools exist — but that appears intentional for a read-only DoD reference service.

    Completeness3/5

    The read-only lifecycle (fetch criteria, check evidence, lint AC, diff versions) is covered, but check_dod returns needs_judgment pointing at rubric://dod/{type} and lint points at template://{type} with no tool to retrieve either, creating dead ends unless resources fill the gap. There is also no way to record judgment outcomes or attestations.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers