Skip to main content
Glama

Overseer MCP Server

by freqkflag
GitHub
TypeScript
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

Deploy Server
A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

Provides structured project management through phase-based workflows, enabling planning, execution tracking, compliance checking, and automated documentation for software development projects.

  1. Quick Start
    1. Problem Statement
      1. High-Level Capabilities
        1. Planning
        2. Execution
        3. Enforcement
        4. Environment & Configuration
      2. Intended Tech Stack
        1. Architecture Overview
          1. Example Use Cases
            1. Use Case 1: Phoenix + Supabase Application
            2. Use Case 2: WordPress Infrastructure Repository
            3. Use Case 3: Multi-Phase Feature Development
          2. Installation
            1. Configuration
              1. MCP Client Integration
                1. Cursor IDE
                2. Claude Desktop
                3. Usage Example
                4. Available Tools
              2. Project Structure
                1. Development
                  1. Client-Agnostic Design
                    1. License

                      New MCP Servers

                      MCP directory API

                      We provide all the information about MCP servers via our MCP API.

                      curl -X GET 'https://glama.ai/api/mcp/v1/servers/freqkflag/PROJECT-OVERSEER-MCP'

                      If you have feedback or need assistance with the MCP directory API, please join our Discord server