Skip to main content
Glama

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

Related MCP server: devpulse-mcp

Run it

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

Connect it to Claude Code

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:

{
  "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

Available Tools

2 tools
find_todosFind TODOsA
Read-only

Scan a project folder for TODO, FIXME and HACK comments. Returns file, line and comment text.

Inputs: path (required), tags.

todo_statsTODO statsA
Read-only

Count TODO/FIXME/HACK comments per file, sorted by most first.

Inputs: path (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    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

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      An MCP server that allows AI assistants to manage todo lists stored in a simple markdown file, supporting creation, reading, updating, and deletion of todo items with persistent IDs.
      5
      18 npm
      6
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Zero-config MCP server that gives AI coding assistants a real-time diagnostic snapshot of your local dev environment. Detects framework, running services, recent errors, git state, and provides a health diagnosis in one call.
      3
      532 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A small MCP server for managing todos, enabling assistants like Claude to create, update, and query task lists through natural conversation. Stores everything in a local SQLite database.
      13 npm
      1
      ISC