Skip to main content
Glama
JiaweiLin

GeeksHacking MCP

by JiaweiLin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

GeeksHacking MCP - TODO Management Server

A Model Context Protocol (MCP) server for managing and tracking #TODO comments from source code files.

Overview

GeeksHacking MCP is an MCP server that provides tools and resources for tracking TODO comments scattered across your codebase. It stores TODO items with their source file location and line numbers, making it easy to manage and query pending tasks directly from your development environment.

Related MCP server: todo-tree MCP Server

Features

  • Add TODOs: Register TODO comments from any source file with line number tracking

  • Query TODOs: Retrieve all TODO items for a specific file

  • Persistent Storage: Stores TODO items in a JSON database

  • MCP Integration: Works seamlessly with MCP-compatible clients (like Claude Desktop, Cline, etc.)

Installation

Prerequisites

  • Python 3.13 or higher

  • uv package manager (recommended) or pip

Install via uv

uvx --from git+https://github.com/JiaweiLin/geekshacking-mcp.git todo_mcp

Install from source

# Clone the repository
git clone https://github.com/JiaweiLin/geekshacking-mcp.git
cd geekshacking-mcp

# Install dependencies
uv sync

# Run the server
uv run todo_mcp

Usage

As an MCP Server

Add the following configuration to your MCP client configuration file (e.g., Claude Desktop's config):

{
  "mcpServers": {
    "todo_mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/JiaweiLin/geekshacking-mcp.git",
        "todo_mcp"
      ]
    }
  }
}

Or if installed locally:

{
  "mcpServers": {
    "todo_mcp": {
      "command": "uv",
      "args": ["run", "todo_mcp"],
      "cwd": "/path/to/geekshacking-mcp"
    }
  }
}

Available Tools

tool_add_todo

Add a single #TODO text from a source file.

Parameters:

  • filename (string): Source file containing the #TODO

  • line_num (integer): Line number of the #TODO

  • text (string): #TODO text to add

Example:

{
  "filename": "src/main.py",
  "line_num": 42,
  "text": "Refactor this function for better performance"
}

Available Resources

resource_get_todos_for_file

Get all #TODO texts for a source file.

URI Pattern: todo://{filename}/todos

Parameters:

  • filename (string): Source file containing the #TODO

Returns: Array of TODO text strings (empty array if no TODOs exist for the file)

Example URI: todo://src/main.py/todos

Database

TODO items are stored in a JSON file at:

src/todo_mcp/todo_db.json

The database structure:

{
  "filename.ext": {
    "_10": "TODO text at line 10",
    "_20": "TODO text at line 20"
  }
}

Development

Project Structure

geekshacking-mcp/
├── src/
│   └── todo_mcp/
│       ├── __init__.py
│       ├── todo_mcp.py      # MCP server implementation
│       └── todo_db.py        # Database management
├── pyproject.toml            # Project configuration
├── uv.lock                   # Dependency lock file
└── README.md

Setting up for Development

# Install development dependencies
uv sync

# Run the server locally
uv run todo_mcp

# Run tests (if available)
uv run pytest

Dependencies

  • fastmcp>=2.13.0.2 - FastMCP framework for building MCP servers

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Links

Support

For issues, questions, or contributions, please visit the GitHub repository.

Available Tools

1 tool
tool_add_todoA

Add a single #TODO text from a source file

ParametersJSON Schema
NameRequiredDescriptionDefault
filenameYesSource file containing the #ToDO
line_numYesLine number of the #TODO
textYes#ToDO text to add

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses the basic mutation action but omits details on side effects, duplicate handling, file modification behavior, or authorization needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words. Appropriate length for a simple tool with well-documented parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool is simple but description could mention what happens on duplicate, file existence, or return state. Without output schema, lack of return info is acceptable but edge cases are unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds no additional meaning beyond what is already in the input schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action (add), object (#TODO text), and source (from a source file). It is specific and unambiguous, with no sibling tools to differentiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The sentence only states the function.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 1 tool updatev0.1.0
    • First observedtool_add_todo
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of ambiguity. The single tool has a clear and distinct purpose.

Naming Consistency5/5

Since there is only one tool, there are no inconsistencies in naming patterns. The name itself follows snake_case convention.

Tool Count1/5

A single tool is extremely limited for a server, especially when the domain is not explicitly narrow. This feels like an extreme mismatch between scope and tool count.

Completeness2/5

The server only offers a tool to add a TODO, with no tools for listing, updating, or deleting TODOs. This is a significant gap for basic task management functionality.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • t-rush-mcp

    DevDs1989
    A
    license
    A
    quality
    B
    maintenance
    Exposes technical debt management to AI coding assistants, enabling them to find, prioritize, and resolve TODO/FIXME/BUG comments across codebases via MCP tools.
    6
    52 npm
    1
    MIT

  • todo-mcp

    adrianhardy
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables managing tasks in a structured TODO.md file through MCP tools for listing, adding, updating, setting status, logging notes, searching, and removing tasks while preserving hand-authored formatting.
    6 npm
    MIT