# Project Tracker MCP Server

A Model Context Protocol (MCP) server for managing projects, epics, and stories. This allows AI agents (Claude, GPT-5, etc.) to interact with your project tracking system in a structured way.

## Features

- **Hierarchical Structure**: Projects → Epics → Stories
- **Issue Tracking**: Bug tracking, technical debt, and project issues tied to projects
- **PostgreSQL Backend**: Persistent storage with relational database
- **MCP Integration**: Compatible with Claude Desktop, GPT agents, and other MCP clients
- **Full CRUD Operations**: Create, read, update, and delete for all entities
- **Content Storage**: Store summaries, status updates, and conversation context
- **No File Clutter**: AI-generated content stored in database instead of markdown files
- **40 Tools**: Comprehensive API for managing all aspects of project tracking

## Setup

### 1. Install Dependencies

```bash
npm install
```

### 2. Configure Database

Create a `.env` file based on `.env.example`:

```bash
cp .env.example .env
```

Edit `.env` and set your PostgreSQL connection details:

```
DATABASE_URL=postgresql://username:password@localhost:5432/project_tracker
```

### 3. Create Database and Run Migrations

Create the database in PostgreSQL:

```sql
CREATE DATABASE project_tracker;
```

Then run the migration script to create tables:

```bash
npm run build
npm run db:migrate
```

### 4. Start the Server

```bash
npm run dev
```

Or for production:

```bash
npm run build
npm start
```

## Database Schema

### Projects
- `id`: UUID (Primary Key)
- `name`: VARCHAR(255)
- `description`: TEXT
- `status`: VARCHAR(50) (active, on_hold, completed, archived)
- `created_at`: TIMESTAMP
- `updated_at`: TIMESTAMP

### Epics
- `id`: UUID (Primary Key)
- `project_id`: UUID (Foreign Key → projects)
- `name`: VARCHAR(255)
- `description`: TEXT
- `status`: VARCHAR(50) (idea, planned, in_progress, completed, cancelled)
- `priority`: VARCHAR(50) (low, medium, high, critical)
- `created_at`: TIMESTAMP
- `updated_at`: TIMESTAMP

### Stories
- `id`: UUID (Primary Key)
- `epic_id`: UUID (Foreign Key → epics)
- `title`: VARCHAR(255)
- `description`: TEXT
- `status`: VARCHAR(50) (todo, in_progress, review, done, blocked)
- `priority`: VARCHAR(50) (low, medium, high, critical)
- `estimated_hours`: INTEGER
- `actual_hours`: INTEGER
- `created_at`: TIMESTAMP
- `updated_at`: TIMESTAMP

## MCP Tools Available

### Project Management
- `create_project`: Create a new project
- `list_projects`: List all projects with optional status filter
- `get_project`: Get project details with all epics and stories
- `update_project`: Update project information
- `delete_project`: Delete a project (cascades to epics and stories)

### Epic Management
- `create_epic`: Create a new epic in a project
- `list_epics`: List epics for a project
- `get_epic`: Get epic details with all stories
- `update_epic`: Update epic information
- `delete_epic`: Delete an epic (cascades to stories)

### Story Management
- `create_story`: Create a new story in an epic
- `list_stories`: List stories for an epic
- `get_story`: Get story details
- `update_story`: Update story information
- `delete_story`: Delete a story

### Summary Management
- `create_summary`: Save AI-generated summaries
- `list_summaries`: List summaries with filters
- `get_summary`: Get specific summary
- `search_summaries`: Full-text search
- `update_summary`: Update summary
- `delete_summary`: Remove summary

### Status Update Management
- `create_status_update`: Track progress, blockers, achievements
- `list_status_updates`: List status updates with filters
- `get_status_update`: Get specific status update
- `search_status_updates`: Search status updates
- `update_status_update`: Update status update
- `delete_status_update`: Remove status update

### Context Management
- `create_context`: Save conversation context and decisions
- `list_context`: List context entries with filters
- `get_context`: Get specific context
- `search_context`: Search saved context
- `update_context`: Update context
- `delete_context`: Remove context

### Issue Tracking
- `create_issue`: Report bugs, technical debt, security issues
- `list_issues`: List issues with filters (severity, status, assigned_to)
- `get_issue`: Get specific issue details
- `search_issues`: Search issues by keyword
- `update_issue`: Update issue status, assignment, resolution
- `delete_issue`: Remove issue

### Utility
- `get_project_summary`: Get a comprehensive overview of all projects

## Using with AI Agents

### Claude Desktop

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "project-tracker": {
      "command": "node",
      "args": ["__BASE_DIR__/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://username:password@localhost:5432/project_tracker"
      }
    }
  }
}
```

### Other MCP Clients

Connect via stdio transport to the compiled JavaScript file.

## Example Usage

Once connected, AI agents can:

```
Create a project called "Mobile App Redesign"
→ Creates project in database

Add an epic "User Authentication" to the Mobile App Redesign project
→ Creates epic linked to project

Create a story "Implement login form" in the User Authentication epic
→ Creates story linked to epic

Create a status update for this sprint
→ Saves status report in database instead of markdown file

Save this conversation as context
→ Preserves discussion for future reference

Show me all projects with their current status
→ Retrieves and displays all projects

Get detailed view of Mobile App Redesign project
→ Shows project with all epics and stories
```

## Additional Documentation

- **[Status Updates & Context Storage Guide](STATUS_AND_CONTEXT_GUIDE.md)** - Learn how to use the new content storage features
- **[MCP Configuration](MCP_CONFIG.md)** - Detailed setup for VS Code and Claude Desktop
- **[Examples](EXAMPLES.md)** - Code examples and usage patterns
- **[Setup Guide](SETUP.md)** - Complete installation instructions
- **[Quick Start](QUICKSTART.md)** - Get running in 5 minutes

## Development

Watch mode for development:

```bash
npm run watch
```

Then in another terminal:

```bash
npm start
```

### Available Scripts

- `npm run build` - Compile TypeScript
- `npm start` - Run the server
- `npm run dev` - Build and run
- `npm run watch` - Watch mode for development
- `npm run db:migrate` - Run database migrations
- `npm run db:verify` - Verify database schema
- `npm run db:test` - Test database connection
- `npm run db:diagnose` - Diagnose database issues

## License

MIT