Overseer MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Overseer MCP Server plan a new project for our e-commerce platform with phases for design, development, testing, and launch"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 startSee 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:
Enforcing structure through phase-based project management
Tracking progress with clear status indicators and artifacts
Validating completeness before advancing to next phases
Maintaining documentation automatically as projects evolve
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
yamlpackage)File System: Native Node.js
fs/promisesTransport: 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:
overseer.plan_projectcreates phase structureoverseer.run_phaseexecutes each phase sequentiallyoverseer.statustracks progress across all phasesoverseer.check_compliancevalidates before deploymentoverseer.generate_cicreates 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:
overseer.plan_projectsets up infrastructure phasesoverseer.infer_phasesdetects existing Terraform/K8s configsoverseer.sync_docskeeps infrastructure docs updatedoverseer.env_maptracks environment variablesoverseer.secrets_templategenerates 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:
overseer.plan_projectadds new phases to existing projectoverseer.run_phaseexecutes feature developmentoverseer.advance_phasemoves through lifecycleoverseer.lint_repoensures code qualityoverseer.statusprovides visibility to team
Installation
See RUNNING.md for detailed installation and setup instructions.
Quick start:
npm install
npm run build
npm startConfiguration
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 projectDevelopment
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 -dClient-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 toolsoverseer.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
Scored across 12 tools
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.
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.
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.
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
Transform project ideas into paint-by-numbers development plans with phases, tasks, and subtasks.
Plan and run internal projects with compliance: phases, tasks, budget, risks, obligations.
Manage functional-safety requirements and lifecycle traceability.
Manage SysML2 projects; check, evaluate, verify, query, document and diagram models.