MCP TODO Scanner

A Model Context Protocol (MCP) server that scans codebases for TODO comments and exposes them as structured data to LLMs. This enables AI assistants to inspect outstanding work, propose fixes, prioritize tasks, and generate patches.

Features

• Multi-language support: Detects TODOs in 30+ programming languages (JavaScript, TypeScript, Python, Go, Rust, Java, etc.)
• Metadata parsing: Supports structured TODOs with owners, priorities, and estimates
• Flexible scanning: Include/exclude patterns, custom root directories
• Context-aware: Provides surrounding code lines for each TODO
• Caching: In-memory caching for performance
• Read-only: Safe filesystem access with security boundaries

Usage

As an MCP Server

Add to your MCP client configuration:

{
  "mcpServers": {
    "code-todo": {
      "args": [
        "-y",
        "mcp-code-todo@latest"
      ],
      "command": "npx"
    }
  }
}

With Explicit Workspace Root

You can optionally specify the workspace root directory via the --workspace-root argument:

{
  "mcpServers": {
    "code-todo": {
      "args": [
        "-y",
        "mcp-code-todo@latest",
        "--workspace-root",
        "/path/to/your/project"
      ],
      "command": "npx"
    }
  }
}

This is useful when the workspace cannot be auto-detected from environment variables.

MCP Resources

todo://list

Returns all TODOs in the project with metadata.

{
  "todos": [
    {
      "id": "abc123",
      "text": "Implement error handling",
      "filePath": "src/utils.ts",
      "line": 42,
      "language": "typescript",
      "meta": {
        "owner": "ash",
        "priority": "high",
        "estimate": "2h"
      }
    }
  ],
  "meta": {
    "scannedAt": "2024-01-17T22:00:00.000Z",
    "fileCount": 15
  }
}

todo://file/{path}

Returns TODOs for a specific file.

MCP Tools

scan_todos

Scan the codebase for TODO comments.

Parameters:

• root (string, optional): Root directory to scan (defaults to workspace root)
• include (string[], optional): Glob patterns for files to include
• exclude (string[], optional): Glob patterns for files to exclude

Example:

{
  "root": "/path/to/project",
  "include": ["*.ts", "*.js"],
  "exclude": ["test/**", "node_modules/**"]
}

explain_todo

Get more context for a specific TODO item.

Parameters:

• id (string): The unique ID of the TODO item
• contextLines (number, optional): Number of context lines (default: 5)

Returns:

{
  "todo": { "id": "abc123", "text": "...", ... },
  "context": "   39: function example() {\n>  42: // TODO: Implement error handling\n   43:   return data;\n   44: }"
}

group_todos_by_topic

Group TODOs by various criteria.

Returns:

{
  "by-file": {
    "src/utils": [todo1, todo2],
    "src/components": [todo3]
  },
  "by-priority": [high_priority_todos],
  "with-owner": [assigned_todos],
  "unassigned": [unassigned_todos]
}

MCP Prompts

find_todos_in_app

A guided workflow to discover and investigate TODOs in the current app.

Parameters:

• focus (string, optional): Area to focus on, such as auth, payments, frontend, or src/components
• include (string[], optional): Glob patterns to narrow the scan
• exclude (string[], optional): Glob patterns to skip generated or irrelevant paths

Workflow:

1. Confirms workspace with get_workspace (sets it with set_workspace if needed)
2. Runs scan_todos across the codebase
3. Applies any provided focus, include, or exclude filters
4. Summarizes results by count, key files, owners, and priorities
5. Highlights the most important or risky TODOs first
6. Uses explain_todo for deeper inspection when needed
7. Optionally calls group_todos_by_topic to cluster by file, priority, or ownership
8. Recommends the next TODOs to tackle and why

Example usage:

{
  "focus": "auth",
  "include": ["src/**/*.ts"],
  "exclude": ["test/**", "generated/**"]
}

TODO Syntax

Basic TODOs

// TODO: Implement error handling
# TODO: Add validation
/* TODO: Refactor this function */

Structured TODOs

// TODO(ash): Implement error handling
// TODO[@ash][priority=high][est=2h]: Fix performance issue
// TODO(priority=medium): Add unit tests

Supported Metadata

• owner: Assignee name (TODO(owner) or TODO[@owner])
• priority: Priority level ([priority=low|medium|high])
• estimate: Time estimate ([est=2h])

Supported Languages

• JavaScript / TypeScript / JSX / TSX
• Python
• Ruby
• Go
• Rust
• Java / Kotlin
• C / C++ / C#
• Swift
• PHP
• HTML / CSS / SCSS / LESS
• SQL
• Lua
• Perl
• R
• Shell scripts (Bash, Zsh)
• Configuration files (YAML, TOML, INI)
• And more...

Configuration

Default Exclusions

The scanner automatically excludes:

• node_modules, .git, .svn, .hg
• dist, build, out
• .next, .nuxt, coverage
• __pycache__, .pytest_cache
• venv, .venv, env
• vendor, target, bin, obj
• IDE folders (.idea, .vscode)
• OS files (.DS_Store)

File Size Limits

• Maximum file size: 1MB
• Binary files are automatically skipped

Development

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run in development
node ./build/index.js

Project Structure

mcp-code-todo/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── scanner.ts        # TODO extraction and caching
│   ├── languages.ts      # Language comment syntax registry
│   ├── types.ts          # TypeScript interfaces
│   └── utils.ts          # File system utilities
├── build/                # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Security

• Read-only access: No file modification capabilities
• Path validation: Root directory must be explicitly provided
• Binary file filtering: Automatic skipping of binary files
• Size limits: Protection against extremely large files
• No network access: Local filesystem only

License

ISC

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Examples

LLM Workflow

1. LLM calls scan_todos to get all TODOs
2. MCP returns structured TODO list
3. LLM groups TODOs by theme or file
4. LLM calls explain_todo for context on specific items
5. LLM proposes code changes (using separate write-capable MCP)

Sample TODO Detection

// Input file src/utils.ts
export function processData(data: any) {
  // TODO(ash)[priority=high][est=1h]: Add input validation
  return data.map(item => {
    // TODO: Handle null values
    return item.value;
  });
}

// Output from scan_todos
{
  "todos": [
    {
      "id": "abc123",
      "text": "Add input validation",
      "filePath": "src/utils.ts",
      "line": 2,
      "language": "typescript",
      "meta": {
        "owner": "ash",
        "priority": "high",
        "estimate": "1h"
      }
    },
    {
      "id": "def456",
      "text": "Handle null values",
      "filePath": "src/utils.ts",
      "line": 5,
      "language": "typescript"
    }
  ]
}