todo-scout
# 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
Scored across 2 tools
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.
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.
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.
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.