# 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:

```json
{
  "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:

```json
{
  "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.

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "focus": "auth",
  "include": ["src/**/*.ts"],
  "exclude": ["test/**", "generated/**"]
}
```

## TODO Syntax

### Basic TODOs
```javascript
// TODO: Implement error handling
# TODO: Add validation
/* TODO: Refactor this function */
```

### Structured TODOs
```javascript
// 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

```bash
# 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
```typescript
// 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;
  });
}
```

```json
// 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"
    }
  ]
}
```