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

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]
}

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"
    }
  ]
}