MCP Project Tracker

A Model Context Protocol (MCP) server for tracking and managing multiple projects with Claude Code.

Features

• Project Tracking: Track multiple projects with context preservation
• Metadata Storage: Store project metadata including git branch, automation status, and active tasks
• Project Search: Search and filter projects by name, path, or type
• Service Discovery: Automatically discover project-specific tracking services and automation daemons
• Database Queries: Query project tracking databases directly
• Project Switching: Optional integration with external project managers for seamless switching
• Context Preservation: Maintain context when switching between projects

Installation

1. Install Dependencies

pip install -r requirements.txt

2. Run Setup

python3 setup.py

The setup script will:

• Create a config.json file with your preferences
• Initialize the SQLite database with the proper schema
• Create necessary directories
• Generate a README file

3. Configure Claude Code

Add the MCP server to your Claude Code configuration file (usually ~/.claude_code_mcp.json):

{
  "mcpServers": {
    "project-tracker": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp-project-tracker/src/server.py"]
    }
  }
}

Replace /absolute/path/to/ with the actual path to your installation.

Configuration

The config.json file contains all settings. See config.example.json for detailed documentation.

Key Configuration Options

{
  "database": {
    "path": "/home/username/.mcp_project_tracker.db"
  },
  "projects": {
    "root_directory": "/home/username/Projects",
    "auto_discover": true
  },
  "project_manager": {
    "enabled": false,
    "script_path": ""
  },
  "tracking": {
    "auto_track_daemons": true,
    "track_git_branches": true,
    "track_automation_status": true
  }
}

Configuration Fields

• database.path: Full path to the SQLite database file (will be created if it doesn't exist)
• projects.root_directory: Root directory where your projects are stored
• projects.auto_discover: Automatically discover and track projects in the root directory
• project_manager.enabled: Enable integration with an external project manager script
• project_manager.script_path: Path to your project manager script (if enabled)
• tracking.auto_track_daemons: Automatically detect automation daemons in projects
• tracking.track_git_branches: Track and store git branch information
• tracking.track_automation_status: Track automation status and active tasks

Usage

Once configured with Claude Code, you can use the following MCP tools:

Available Tools

1. list_projects

   • Lists all tracked projects with their status, automation state, git branch, and last accessed time
   • Returns: Array of projects with metadata

2. get_project_context

   • Gets detailed context for a specific project
   • Parameters: project_path (string)
   • Returns: Full project context including tasks, git info, and metadata

3. switch_project

   • Switches to a different project, preserving context
   • Parameters: project_path (string)
   • Returns: Success status and project information

4. get_project_stats

   • Gets statistics about all tracked projects
   • Returns: Counts by type, automation coverage, recently accessed projects

5. search_projects

   • Searches for projects by name, path, or type
   • Parameters: query (string)
   • Returns: Matching projects

6. get_recent_switches

   • Gets recent project context switches
   • Parameters: limit (number, optional, default: 10)
   • Returns: Array of recent switches with timestamps and reasons

7. update_project_context

   • Updates or saves context for a specific project
   • Parameters: project_path (string), context_data (object)
   • Returns: Success status

8. discover_project_services

   • Discovers tracking services and databases within a specific project
   • Parameters: project_path (string)
   • Returns: List of discovered services (daemons, databases, state files)

9. scan_all_services

   • Scans all tracked projects to discover their tracking services
   • Returns: Summary of all projects with services

10. query_tracking_database

    • Queries a project-specific tracking database
    • Parameters: db_path (string), query (string, optional)
    • Returns: Schema information and query results

Database Schema

project_contexts Table

Stores project metadata and context information:

Column	Type	Description
project_path	TEXT (PRIMARY KEY)	Full path to the project
project_name	TEXT	Human-readable project name
project_type	TEXT	Type of project (e.g., "python", "web", "nodejs")
last_accessed	TEXT	ISO timestamp of last access
automation_status	TEXT	Automation status (e.g., "active", "inactive")
git_branch	TEXT	Current git branch
active_tasks	TEXT (JSON)	Array of active tasks
context_data	TEXT (JSON)	Additional context data
mcp_session_id	TEXT	MCP session identifier
created_at	TEXT	ISO timestamp of creation

Indexes:

• idx_last_accessed on last_accessed DESC
• idx_project_type on project_type

context_switches Table

Tracks context switches between projects:

Column	Type	Description
id	INTEGER (PRIMARY KEY)	Auto-incrementing ID
from_project	TEXT	Source project path
to_project	TEXT	Destination project path
switch_time	TEXT	ISO timestamp of switch
context_preserved	INTEGER	1 if context was preserved, 0 otherwise
switch_reason	TEXT	Reason for the switch

Indexes:

• idx_switch_time on switch_time DESC

Example: Using with Claude Code

Once configured, you can ask Claude Code:

• "List all my tracked projects"
• "Switch to the web-app project"
• "Show me recent project switches"
• "What services are running in my backend project?"
• "Search for all Python projects"
• "Update the context for my current project with this task list"

Advanced Usage

Custom Project Manager Integration

If you have an external project manager script, you can integrate it:

1. Set project_manager.enabled to true in config.json
2. Set project_manager.script_path to your script's path
3. Your script should accept --switch <project_path> arguments

Example script interface:

python3 /path/to/project_manager.py --switch /path/to/project

Discovering Project Services

The tracker can automatically discover:

• Automation daemons (.automation/auto_track_daemon.py)
• Tracking databases (tracking.db, .automation/tracking.db, frontend/tracking.db)
• Development state files (.automation/state/development_state.json)

Use discover_project_services to scan a specific project or scan_all_services to scan all tracked projects.

Querying Project Databases

You can query any SQLite database within your projects:

{
  "db_path": "/path/to/project/tracking.db",
  "query": "SELECT * FROM commits ORDER BY timestamp DESC LIMIT 10"
}

If no query is provided, the tool returns the database schema and sample data from each table.

Troubleshooting

Database Not Found

• Run python3 setup.py to initialize the database
• Check that database.path in config.json is correct

Project Not Found

• Use update_project_context to manually add a project
• Enable auto_discover in config.json
• Verify projects.root_directory is correct

Permission Errors

• Ensure the database path is writable
• Check that project directories are accessible

Architecture

mcp-project-tracker/
├── src/
│   └── server.py          # MCP server implementation
├── config.json            # Your configuration (created by setup)
├── config.example.json    # Example configuration with documentation
├── setup.py              # Interactive setup script
├── requirements.txt      # Python dependencies
└── README.md            # This file

Dependencies

• mcp (>=1.0.0): Model Context Protocol SDK
• sqlite3: Database storage (included with Python)
• json: Configuration and serialization (included with Python)
• pathlib: Path handling (included with Python)

License

MIT License - feel free to modify and distribute.

Contributing

This is a generic version designed to be customizable for any workflow. Feel free to:

• Add new tracking features
• Extend the database schema
• Create custom integrations
• Share your improvements

Support

For issues or questions:

1. Check the configuration in config.json
2. Review the database schema
3. Verify Claude Code MCP configuration
4. Check file permissions and paths