Skip to main content
Glama
Sign In
debt-mcp

debt-mcp

by 0xmortuex
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

debt-mcp, the hard way

Build a small version of debt-mcp from scratch: an MCP server that finds TODO / FIXME markers in a repository and tells you how old each one is and who added it, using real git blame.

By the end you will have written, in about 500 lines of dependency-free Python:

  • a comment tokenizer that does not report "TODO" inside strings or URLs,

  • a marker parser (TODO(alice):, FIXME[JIRA-9], #123) with a strict word rule,

  • a git blame --porcelain reader,

  • exact age and author attribution, including uncommitted and untracked lines,

  • "stale in a busy file vs stale in a dead file" analysis from git log,

  • suppression counts (# noqa, @ts-ignore, ...), long functions and commented-out code,

  • an MCP wrapper with a directory sandbox, tested over real stdio.

The real server does the same things with more languages and more care; the final chapter lists the gaps.

Chapters

#

Chapter

You learn

1

Comments, not grep

a one-pass tokenizer; why strings, URLs and $# break grep

2

Marker parsing

the "first word of a comment" rule; annotations; the false-positive corpus

3

git blame --porcelain

the format, -w -M -L, uncommitted lines, running git safely

4

Age and author

scan + blame, exact ages with a pinned clock, scripted repos

5

Stale: hot or dead

git log activity; why an old TODO in a busy file is the worst kind

6

Suppression signals

other cheap debt signals, counted only inside real comments

7

The MCP wrapper

tools, ToolError, a path sandbox, a stdio test

Every chapter has prose, runnable code (in debtlite/) and a main.py that checks its own claims with assert.

Related MCP server: promptpack

Run it

Needs Python 3.10+ and git.

pip install -r requirements.txt
python verify.py          # all chapters, exactly what CI runs
python verify.py 03 04    # some chapters
python 04-age-and-author/main.py

verify.py is the source of truth: if a chapter's code and its README disagree, CI fails. The tests build real git repositories in a temp directory with fixed authors and dates (GIT_AUTHOR_DATE and friends), so ages are exact and identical on every machine.

MIT licensed.

This server cannot be deployed

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • modelroute

    modelrouteofficial

    cognis-digital
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to scan code for TODO, FIXME, XXX issues via MCP, providing prioritized findings in table, JSON, or SARIF format.
    -

  • promptpack

    cognis-digital
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to scan codebases for prioritized findings (TODO, FIXME, XXX) and retrieve results in table, JSON, or SARIF format via MCP.
    -

  • skillhub

    cognis-digital
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to scan codebases for TODO/FIXME/XXX patterns and get prioritized results over MCP, supporting CI gates and multiple output formats.
    -

  • mcp-code-todo

    ashhitch
    A
    license
    A
    quality
    D
    maintenance
    Scans codebases for TODO comments and exposes them as structured data to LLMs, enabling AI assistants to inspect, prioritize, and propose fixes.
    5
    5 npm
    ISC