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