Skip to main content
Glama
README.md
# todo-scout-mcp

A tiny MCP server that lets any AI assistant find TODOs, FIXMEs and HACKs in your codebase.
Built in the video **"MCP Explained in 8 Minutes (Build Your First Server)"**.

**Receipts:** about 100 lines of TypeScript · $0 to run (local, no API key) · ~20 min to build.

## What it exposes

| Type | Name | What it does |
|---|---|---|
| Tool | `find_todos` | Scans a folder and returns `file:line [TAG] text` |
| Tool | `todo_stats` | Counts items per file, most first |
| Resource | `todo-scout://guide` | Triage rules the AI can read |

## Run it

```bash
npm install
npm test        # builds, starts the server, calls every tool against ./example-project
```

## Connect it to Claude Code

```bash
npm run build
claude mcp add todo-scout -- node "$(pwd)/dist/index.js"
```

Then ask: *"Use todo-scout to find the FIXMEs in /path/to/my/project and fix the worst one."*

## Connect it to Claude Desktop / Cursor

Add to the app's MCP config:

```json
{
  "mcpServers": {
    "todo-scout": { "command": "node", "args": ["/ABSOLUTE/PATH/demo-repo/dist/index.js"] }
  }
}
```

## The one gotcha

Never `console.log` in a stdio MCP server. Stdout is the protocol channel, so log to stderr (`console.error`).

MIT License

TDQS

A3.6/5.0

Scored across 2 tools

Disambiguation4/5

The two tools are closely related since todo_stats is essentially an aggregate view of find_todos output, so an agent could occasionally pick the wrong one when it just needs counts vs. full details. However, the descriptions make the distinction reasonably clear: detailed scan vs. per-file counts.

Naming Consistency4/5

Both names use snake_case, which is consistent, but the conventions differ slightly (verb-first find_todos vs. noun-first todo_stats). Still readable and predictable enough that an agent can infer behavior from the names.

Tool Count3/5

Two tools is thin for a scanning server; a single scan tool with a mode or filter option could plausibly replace both. It is not egregious, but the surface feels minimal and the second tool is a narrow derivative of the first.

Completeness3/5

The core lifecycle of scanning and summarizing TODOs is covered, but obvious operations are missing: filtering by tag or severity, excluding directories, or scoping to specific file types. Agents can work around some of this client-side, but the surface is notably limited.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues