# Overseer MCP Server

**Version**: 1.0.0

A standalone Model Context Protocol (MCP) server that implements Overseer multi-agent behavior for structured project management. Overseer provides planning, execution, and enforcement capabilities for managing software projects through well-defined phases.

## Quick Start

```bash
# Install dependencies
npm install

# Build
npm run build

# Run
npm start
```

See [RUNNING.md](./RUNNING.md) for detailed installation and deployment instructions.

## Problem Statement

Modern software development involves complex workflows with multiple phases: planning, implementation, testing, deployment, and maintenance. Without structured oversight, projects can:

- **Lose track of progress** across multiple workstreams
- **Skip critical steps** in development lifecycle
- **Lack visibility** into what's been completed vs. what's pending
- **Struggle with consistency** across team members and projects
- **Miss documentation** and artifact requirements

Overseer exists to solve these problems by:

1. **Enforcing structure** through phase-based project management
2. **Tracking progress** with clear status indicators and artifacts
3. **Validating completeness** before advancing to next phases
4. **Maintaining documentation** automatically as projects evolve
5. **Providing tooling** that works with any MCP-compatible client

## High-Level Capabilities

### Planning
- **Project Planning**: Create phase definitions from templates or custom specifications
- **Phase Inference**: Automatically detect phases from existing project structure
- **Template Management**: Use predefined phase templates or create custom ones

### Execution
- **Phase Execution**: Run specific phases with validation and artifact tracking
- **Phase Advancement**: Move phases through lifecycle (pending → active → completed)
- **Status Tracking**: Real-time visibility into project and phase status

### Enforcement
- **Compliance Checking**: Validate that phases meet completion criteria
- **Linting**: Ensure code and documentation meet standards
- **Documentation Sync**: Keep project docs in sync with actual implementation

### Environment & Configuration
- **Environment Mapping**: Track and manage environment variables across phases
- **CI/CD Generation**: Generate CI/CD pipelines from phase definitions
- **Secrets Management**: Create templates for secure credential management

## Intended Tech Stack

- **Runtime**: Node.js 18+ (ESM modules)
- **Language**: TypeScript 5.3+
- **MCP SDK**: `@modelcontextprotocol/sdk` (v0.5.0+)
- **Configuration**: YAML (via `yaml` package)
- **File System**: Native Node.js `fs/promises`
- **Transport**: stdio (standard MCP transport)

## Architecture Overview

Overseer operates as a **pure MCP server** with no client-specific dependencies:

```
┌─────────────────┐
│  MCP Client     │  (Cursor, Claude, Nova, or any MCP client)
│  (any client)   │
└────────┬────────┘
         │ MCP Protocol (stdio/SSE/HTTP)
         │
┌────────▼─────────────────────────────┐
│     Overseer MCP Server              │
│  ┌─────────────────────────────────┐ │
│  │  Tool Layer                     │ │
│  │  (plan_project, run_phase, etc)│ │
│  └────────────┬────────────────────┘ │
│  ┌────────────▼────────────────────┐ │
│  │  Core Logic Layer               │ │
│  │  - PhaseManager                 │ │
│  │  - RepoHandler                  │ │
│  │  - ConfigLoader                 │ │
│  └────────────┬────────────────────┘ │
└───────────────┼──────────────────────┘
                │
┌───────────────▼──────────────────────┐
│  File System                         │
│  - ~/dev/{repo}/PHASES.md           │
│  - ~/dev/{repo}/PHASE-*.md          │
│  - config/sentinel.yml              │
└──────────────────────────────────────┘
```

## Example Use Cases

### Use Case 1: Phoenix + Supabase Application

**Scenario**: Building a full-stack web application with Elixir/Phoenix backend and Supabase frontend.

```json
{
  "repo_name": "phoenix-supabase-app",
  "phases": [
    "planning",
    "database-design",
    "backend-api",
    "frontend-integration",
    "testing",
    "deployment"
  ]
}
```

**Workflow**:
1. `overseer.plan_project` creates phase structure
2. `overseer.run_phase` executes each phase sequentially
3. `overseer.status` tracks progress across all phases
4. `overseer.check_compliance` validates before deployment
5. `overseer.generate_ci` creates CI/CD pipeline

### Use Case 2: WordPress Infrastructure Repository

**Scenario**: Managing infrastructure-as-code for WordPress hosting.

```json
{
  "repo_name": "wordpress-infra",
  "phases": [
    "infrastructure-planning",
    "terraform-setup",
    "kubernetes-config",
    "monitoring-setup",
    "security-hardening",
    "documentation"
  ]
}
```

**Workflow**:
1. `overseer.plan_project` sets up infrastructure phases
2. `overseer.infer_phases` detects existing Terraform/K8s configs
3. `overseer.sync_docs` keeps infrastructure docs updated
4. `overseer.env_map` tracks environment variables
5. `overseer.secrets_template` generates secrets management structure

### Use Case 3: Multi-Phase Feature Development

**Scenario**: Adding a new feature to an existing project.

```json
{
  "repo_name": "existing-project",
  "phases": ["feature-planning", "implementation", "testing", "documentation"]
}
```

**Workflow**:
1. `overseer.plan_project` adds new phases to existing project
2. `overseer.run_phase` executes feature development
3. `overseer.advance_phase` moves through lifecycle
4. `overseer.lint_repo` ensures code quality
5. `overseer.status` provides visibility to team

## Installation

See `RUNNING.md` for detailed installation and setup instructions.

Quick start:

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

## Configuration

The server reads configuration from `config/sentinel.yml`. See `DESIGN.md` for detailed configuration schema.

## MCP Client Integration

### Cursor IDE

Add to your Cursor MCP configuration (typically in Cursor settings or `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "overseer": {
      "command": "node",
      "args": ["/absolute/path/to/overseer-mcp/dist/server.js"],
      "env": {
        "OVERSEER_BASE_PATH": "~/dev"
      }
    }
  }
}
```

**Using Docker:**

```json
{
  "mcpServers": {
    "overseer": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "~/dev:/root/dev:ro",
        "-v", "/absolute/path/to/overseer-mcp/config:/app/config:ro",
        "freqkflag/overseer-mcp:latest"
      ]
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "overseer": {
      "command": "node",
      "args": ["/absolute/path/to/overseer-mcp/dist/server.js"]
    }
  }
}
```

### Usage Example

Once configured, you can use Overseer tools in your MCP client:

**Plan a project:**
```json
{
  "repo_root": "~/dev/sample-project",
  "project_name": "sample-project",
  "project_summary": "A sample web application",
  "overwrite_existing": false
}
```

**Run a phase:**
```json
{
  "repo_root": "~/dev/sample-project",
  "phase_id": "01",
  "aggression_level": "normal"
}
```

**Advance phase:**
```json
{
  "repo_root": "~/dev/sample-project",
  "expected_current_phase": "01"
}
```

See `DEMO.md` for a complete walkthrough.

### Available Tools

See `TOOLS.md` for complete tool documentation.

## Project Structure

```
overseer-mcp/
├── config/
│   └── sentinel.yml          # Configuration file
├── src/
│   ├── core/
│   │   ├── config.ts        # Configuration loader
│   │   ├── phase-manager.ts # Phase management logic
│   │   ├── repo.ts          # Repository file operations
│   │   ├── repo-analyzer.ts # Repository structure analysis
│   │   └── fsUtils.ts       # File system utilities
│   ├── tools/
│   │   ├── plan-project.ts  # Project planning
│   │   ├── infer-phases.ts  # Phase inference
│   │   ├── update-phases.ts # Phase updates
│   │   ├── run-phase.ts     # Phase execution
│   │   ├── advance-phase.ts # Phase advancement
│   │   ├── status.ts         # Project status
│   │   ├── lint-repo.ts     # Repository linting
│   │   ├── sync-docs.ts     # Documentation sync
│   │   ├── check-compliance.ts # Compliance checking
│   │   ├── env-map.ts       # Environment mapping
│   │   ├── generate-ci.ts   # CI/CD generation
│   │   ├── secrets-template.ts # Secrets templates
│   │   └── index.ts         # Tool registration
│   └── server.ts            # MCP server entry point
├── config/
│   └── sentinel.yml         # Configuration
├── Dockerfile               # Docker image definition
├── docker-compose.yml      # Docker Compose configuration
├── package.json
├── tsconfig.json
├── README.md                # This file
├── RUNNING.md               # Installation and usage guide
├── DEMO.md                  # Demo scenario walkthrough
├── DESIGN.md                # Architecture and design
├── TOOLS.md                 # Tool documentation
└── PHASES.md                # Build phases for this project
```

## Development

See `RUNNING.md` for detailed instructions.

Quick commands:

```bash
# Build
npm run build

# Development mode with watch
npm run dev

# Run production server
npm start

# Docker
docker-compose up -d
```

## Client-Agnostic Design

Overseer is designed to work with **any MCP-compatible client**:

- **Cursor**: IDE integration via MCP
- **Claude Desktop**: Chat-based interaction
- **Nova**: Code editor integration
- **Custom clients**: Any tool that speaks MCP protocol

All tool interfaces use pure JSON-compatible structures. No client-specific features are required.

## License

MIT