mcp-todo-server

README

MCP Todo Server

Model Context Protocol (MCP) server for managing TODO.md and CHANGELOG.md files.

Features

• Precise, line-based editing and reading of file contents.
• Efficient partial file access using line ranges, for efficient LLM tool usage.
• Retrieve specific file content by specifying line ranges.
• Fetch multiple line ranges from multiple files in a single request.
• Apply line-based patches, correctly adjusting for line number changes.
• Supports a wide range of character encodings (utf-8, shift_jis, latin1, etc.).
• Perform atomic operations across multiple files.
• Robust error handling using custom error types.
• Adheres to Semantic Versioning and Keep a Changelog conventions.
• Model Context Protocol (MCP) server capabilities for seamless integration with LLM tools.

Requirements

• Go v1.23+
• Linux, macOS, or Windows
• File system permissions for read/write operations

Installation

# Install from source
go install codeberg.org/mutker/mcp-todo-server/cmd/mcp-todo-server@latest

Usage

Run the MCP server for integration with Claude Desktop and other MCP clients:

# Run the MCP server
mcp-todo-server

# Run in verbose mode for debugging
mcp-todo-server -verbose

# Run with custom encoding
MCP_DEFAULT_ENCODING=shift_jis mcp-todo-server

# Run with test script to verify functionality
./scripts/test-mcp.sh

Using with MCP Inspector

To test the server with MCP Inspector, run:

# Run with MCP Inspector
npx @modelcontextprotocol/inspector mcp-todo-server -verbose

Configuring with Claude Desktop

To use with Claude Desktop, add this to your configuration at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "todo": {
      "command": "mcp-todo-server"
    }
  }
}

Available MCP Tools

TODO.md Operations

• get-todo-tasks - Get all tasks from TODO.md
• get-todo-tasks-by-version - Get tasks for a specific version
• add-todo-task - Add a new task for a specific version
• update-todo-task - Update an existing task
• add-todo-version - Add a new version section
• import-todo - Import and format an existing TODO.md

CHANGELOG.md Operations

• get-changelog - Get all changelog entries
• get-changelog-by-version - Get changelog entries for a specific version
• add-changelog-entry - Add a new changelog version entry
• update-changelog-entry - Update an existing changelog entry
• import-changelog - Import and format an existing CHANGELOG.md
• generate-changelog-from-todo - Generate a new CHANGELOG.md entry based on completed tasks in TODO.md

Development

# Clone the repository
git clone https://codeberg.org/mutker/mcp-todo-server.git
cd mcp-todo-server

# Build the project
go build -o build/ ./cmd/mcp-todo-server

# Run unit tests
go test ./...

# Run MCP protocol tests
./scripts/test-mcp.sh

Testing Protocol Compatibility

The test script in scripts/test-mcp.sh validates MCP server functionality:

• Protocol initialization
• Tools listing
• Tool execution
• Shutdown/exit sequence

This ensures the server implements the MCP specification correctly and can communicate with MCP clients like Claude Desktop.

MCP Client Integration

The MCP server integrates with MCP clients like Claude Desktop, providing tools for managing TODO.md and CHANGELOG.md files. Usage examples:

• Ask "What are my current tasks for version 0.2.0?"
• Say "Add a new task to implement OAuth authentication for version 0.2.0"
• Request "Generate a changelog entry for version 0.1.0 based on completed tasks"
• Say "Import my existing TODO.md file from /path/to/my/TODO.md"

The server intelligently handles task parsing, version management, and provides rich semantic understanding of tasks and changelog entries.

Thanks

• tumf/mcp-text-editor for the inspiration.
• Model Context Protocol for the MCP specification.

License

MCP Todo Server is licensed under the MIT License. See LICENSE for the full license text.