DevPulse MCP Server

DevPulse is a local project health and context oracle Model Context Protocol (MCP) server. It hooks into your local workspace directories to feed your AI assistant real-time project metrics regarding unresolved technical debt.

Features

• Tool (scan_todos): Scans a target directory recursively for unresolved TODO:, FIXME:, or BUG: comments across code files and returns a structured payload.
• Resource (project://backlog): Dynamically bundles those scanned technical debts into a virtual, read-only Markdown file contextually available to the LLM.
• Prompt (sprint-planner): A template that instructs the AI to analyze outstanding technical debt and construct a clean, prioritized project sprint plan.

Directory Structure

devpulse-mcp/
├── .venv/                      # Isolated virtual environment
├── .gitignore
├── pyproject.toml              # Project metadata and dependencies (FastMCP, Hatchling)
├── README.md                   # Setup, installation, and architectural notes
├── devpulse_config.json        # Configuration snippet for testing in IDEs/Claude Desktop
└── src/
    └── devpulse/
        ├── __init__.py
        ├── server.py           # Core MCP server initialization & orchestration
        ├── tools/
        │   ├── __init__.py
        │   └── scanner.py      # Logic for scanning files for technical debt tags
        └── resources/
            ├── __init__.py
            └── backlog_gen.py  # Generates the virtual markdown resource string.

Installation & Setup

1. Create the virtual environment:

   python -m venv .venv

2. Activate the virtual environment:

   • Windows (PowerShell):

     .venv\Scripts\Activate.ps1

   • Unix/macOS:

     source .venv/bin/activate

3. Install the package in editable mode:

   pip install -e .

Configuration for IDEs/Claude Desktop

Add the following block to your MCP configurations file (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "devpulse": {
      "command": "C:/Users/debnil/projects/devpulse-mcp/.venv/Scripts/python.exe",
      "args": [
        "-m",
        "devpulse.server"
      ],
      "env": {
        "DEVPULSE_PROJECT_ROOT": "C:/Users/debnil/projects/devpulse-mcp"
      }
    }
  }
}

Note: Replace DEVPULSE_PROJECT_ROOT with the path of the project folder you want to scan by default.

Development & Testing

You can use the FastMCP development server to inspect the tools, resources, and prompts:

fastmcp dev src/devpulse/server.py

This starts a developer inspector interface, allowing you to run tools and view resource/prompt templates directly in your browser.