mcpField
T
tododebt

tododebt

Local
github.com/CloudCorpRecordsDeveloper Tools0Updated 1w ago
Repository

About tododebt

tododebt scans source files for TODO, FIXME, HACK, and other selected markers, reporting their locations and counts. It offers a CLI and an MCP server; the MCP tool analyzes supplied file contents without accessing disk.

Key features

  1. 01Scan TODO, FIXME, and HACK markers
  2. 02Report file, line, and text
  3. 03Count by marker and file
  4. 04Choose markers to scan

Use cases

  1. 01Inventory acknowledged technical debt
  2. 02Find pending work in selected source files

MCP support

The MCP server provides `scan_todos`, which accepts files as path-and-content pairs and returns an inventory of matching markers. It does not access disk.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "cloudcorprecords-tododebt": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/tododebt"
      ]
    }
  }
}
Run commandnpx -y @reneturcios/tododebt

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@reneturcios/tododebt0.1.0
ocighcr.io/cloudcorprecords/tododebt:0.1.0

Tools

1

Saved tool list · updated 2w ago

ParameterTypeRequiredDescription
pathstringYesTarget path to check

Details

From the project README

tododebt

How much acknowledged debt is sitting in the codebase? tododebt inventories the markers — TODO, FIXME, HACK by default — across a set of source files and reports every occurrence with its file, 1-based line number, and line text, plus counts in total, by marker, and by file.

A marker counts only as a standalone token (the marker followed by a non-letter), so TODOS and METHOD never false-positive, while TODO:, FIXME(user), and // TODO all count. Only the first marker on a line is reported. Matching is case-sensitive.

The MCP tool takes file contents as input (no disk access); the CLI reads the files you name. Pure local computation: no network, no configuration.

CLI

npx @reneturcios/tododebt scan src/*.ts
npx @reneturcios/tododebt scan README.md src/index.ts --markers TODO,XXX
npx @reneturcios/tododebt --version

Exit codes: 0 on success (a non-empty inventory is a result, not an error), 1 on a runtime error (including an unreadable file), 2 on a usage error.

MCP server

npx -y @reneturcios/tododebt mcp

MCP client config:

{
  "mcpServers": {
    "tododebt": {
      "command": "npx",
      "args": ["-y", "@reneturcios/tododebt", "mcp"]
    }
  }
}
Tools
  • scan_todos — Inventory debt markers across supplied source files.
    • files (array, required) — the files to scan, as {path, content} pairs
    • markers (array of strings, optional) — markers to look for; default TODO, FIXME, HACK

Docker

docker run -i ghcr.io/cloudcorprecords/tododebt
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/tododebt scan /w/src/index.ts

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.