Skip to main content
Glama

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

# Install dependencies
npm install

# Build
npm run build

# Run
npm start

See 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.

{
  "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.

{
  "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.

{
  "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:

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):

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

Using Docker:

{
  "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):

{
  "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:

{
  "repo_root": "~/dev/sample-project",
  "project_name": "sample-project",
  "project_summary": "A sample web application",
  "overwrite_existing": false
}

Run a phase:

{
  "repo_root": "~/dev/sample-project",
  "phase_id": "01",
  "aggression_level": "normal"
}

Advance phase:

{
  "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:

# 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

Available Tools

12 tools
overseer.advance_phaseB

Advance a phase to the next phase after validating all deliverables are complete. Marks current phase as "locked" and sets next phase as current.

Inputs: repo_root (required), expected_current_phase (required).

overseer.check_complianceB

Validates repository structure against sentinel.yml conventions. Checks for expected directories and key files.

Inputs: repo_root (required), phase_id, strict.

overseer.env_mapB

Maps and tracks environment variables across phases, identifying required vs. optional variables.

Inputs: repo_name (required), phase_name.

overseer.generate_ciC

Generates CI/CD pipeline configuration (GitHub Actions, GitLab CI, etc.) based on phase definitions.

Inputs: repo_name (required), ci_type (required), options.

overseer.infer_phasesC

Analyzes an existing repository structure to suggest phase definitions based on detected patterns (files, directories, configs).

Inputs: repo_root (required), options.

overseer.lint_repoB

Detects languages in the repository and recommends linting commands based on coding standards in sentinel.yml.

Inputs: repo_root (required), options.

overseer.plan_projectA

Plan a new project by creating phase definitions. Creates PHASES.md and PHASE-*.md files in the repository. Can infer phases from project structure if not provided.

Inputs: repo_root (required), project_name (required), project_summary, overwrite_existing, +1 more.

overseer.run_phaseA

Execute a specific phase of a project. Reads tasks from PHASE-XX.md, checks completion status, and creates TODOs/stubs for incomplete tasks.

Inputs: repo_root (required), phase_id (required), aggression_level.

overseer.secrets_templateC

Creates a template structure for managing secrets and credentials securely.

Inputs: repo_name (required), template_type.

overseer.statusA

Get the current status of a project, including all phases and their states. Determines phase status from PHASES.md and PHASE-*.md files.

Inputs: repo_root (required).

overseer.sync_docsC

Ensures documentation consistency. Validates that PHASES.md and PHASE-XX.md files follow consistent formatting with required sections.

Inputs: repo_root (required), options.

overseer.update_phasesC

Updates existing phase definitions (rename, modify description, add/remove steps, deliverables, done criteria).

Inputs: repo_root (required), modifications (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have distinct purposes, such as overseer.advance_phase for phase progression and overseer.check_compliance for repository validation, but overseer.plan_project and overseer.infer_phases both involve phase definition, which could cause some confusion. However, their descriptions clarify that plan_project creates phase definitions while infer_phases suggests them, reducing overlap.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with a clear verb_noun structure, such as overseer.advance_phase and overseer.check_compliance. This uniformity makes the tool set predictable and easy to navigate, with no deviations in naming conventions.

    Tool Count5/5

    With 12 tools, the count is well-suited for the server's purpose of project oversight and phase management. Each tool addresses a specific aspect like compliance, documentation, or execution, ensuring comprehensive coverage without being overwhelming or sparse.

    Completeness5/5

    The tool set provides complete lifecycle coverage for project and phase management, including creation (plan_project), execution (run_phase), validation (check_compliance, lint_repo), and updates (update_phases). There are no obvious gaps, as tools handle everything from initial planning to ongoing synchronization and status tracking.

    Related MCP Connectors