PM Governance Server

A complete Model Context Protocol (MCP) server implementation for AI-assisted project management governance across 8 domains: Projects, Governance (RAID), Scope (Goals→KPIs), People (Teams & Availability), Time (Milestones & Demand Planning), Cost (Procurement & Contracts), Meetings, and Administration.

Architecture

MCP Layer (51 tools)
    ↓
Services Layer (10 services + dashboard)
    ↓
Repository Layer (8 typed protocols + base class)
    ↓
Cache Layer (memory, Redis, tiered)
    ↓
HTTP Client Layer (httpx with retries, auth, error mapping)
    ↓
REST Backend (JSON Server-compatible API)

Quick Start

1. Install dependencies:

   pip install -e .
   

2. Configure environment:

   cp .env.example .env
   # Edit .env with your API credentials
   

3. Run the server:

   # Stdio transport (default)
   python main.py
   
   # Or SSE transport (for web clients)
   python main.py --transport sse --port 8080
   

Key Features

• 51 MCP Tools across 8 domains (project, governance, scope, people, time, cost, meeting, admin, dashboard)
• Typed Repository Protocols — inject test mocks without subclassing
• Multi-tier Caching — memory L1 + Redis L2 with TTL per data type
• Input Guardrails — prompt injection detection, validation bounds
• Structured Logging — JSON output via structlog + stdlib
• Telemetry Integration — W&B Weave + OpenTelemetry (optional, no-op if disabled)
• Full DI Container — Settings → ApiClient → Repos → Services → Tools
• MCP Resources — 4 markdown guides embedded in context (API overview, portfolio, governance, scope)
• MCP Prompts — 4 reusable prompt templates (project report, executive briefing, RAID escalation, scope progress)

Domain Model

Projects

• RAG status (overall, schedule, budget, risk)
• Budget baseline / actual / forecast
• Ownership and methodology

Governance (RAID + Change)

• Risks — probability, impact, mitigation, escalation
• Issues — severity, resolution, escalation
• Dependencies — incoming/outgoing/external
• Decisions — meeting log, impact
• Actions — score-based (probability × impact), category, approval gates
• Change Requests — workflow (Submitted → Approved → Implemented)

Scope (Goal Hierarchy)

• Goals — strategic, with status
• Objectives — measurable outcomes per goal
• Benefits — business value per objective
• KPIs — baseline/target/current per benefit
• Stories — Functional or Technical, linked to objectives
• Tasks — estimated hours per story/scope item
• Scope Items — deliverables with status and priority

People (Teams & Availability)

• Teams — named groups with metadata
• Members — hourly rate, weekly availability, role
• Roles — catalogue entries (PM, BA, Developer, etc.)
• Absences — vacation, sick, training, personal with approval status

Time (Schedule & Effort)

• Milestones — with status (On Track, At Risk, Delayed, Completed)
• Demand Planning — hours grid (taskId → {memberKey: hours})
• Timesheets — actual hours + ETC grid

Cost

• Procurement — invoices, vendor spend, cost categories
• Contracts — vendor agreements, lifecycle (Draft → Active → Expired)

Meetings

• Meetings — steering committee, weekly status, stakeholder review
• Reports — published governance documents
• Lessons Learned — approved post-project retrospectives

Admin

• Roles — platform and project roles
• Privileges — granular permission catalogue
• Audit Logs — immutable operation history

Testing

Run the test suite:

pytest tests/ -v

Key fixtures:

• test_settings — test-mode configuration (null cache, fake backend)
• mock_api_client — httpx client for testing
• null_cache — deterministic NullCacheBackend

Environment Variables

See .env.example for all options. Key variables:

Variable	Default	Purpose
API_BASE_URL	http://localhost:4000	PM Governance REST backend
API_KEY	(empty)	Bearer token + X-Api-Key header
CACHE_BACKEND	memory	Cache strategy (memory / redis / tiered)
LOG_LEVEL	INFO	Logging verbosity
LOG_DEV_MODE	false	Console renderer (true) vs JSON (false)
WANDB_API_KEY	(empty)	W&B Weave tracing (optional)
OTEL_ENABLED	false	OpenTelemetry tracing (optional)

File Structure

pm-governance-mcp/
├── main.py                     # Entry point
├── pyproject.toml              # Package metadata
├── .env.example                # Environment template
├── README.md                   # This file
├── src/pm_mcp/
│   ├── __init__.py
│   ├── container.py            # DI container
│   ├── config/
│   │   └── settings.py         # Pydantic-settings
│   ├── client/
│   │   └── api_client.py       # httpx with retry
│   ├── cache/
│   │   └── ttl_cache.py        # Memory / Redis / Tiered
│   ├── exceptions/
│   │   ├── base.py
│   │   ├── infrastructure.py
│   │   ├── domain.py
│   │   ├── validation.py
│   │   └── mcp.py
│   ├── guardrails/
│   │   └── input_guard.py      # Injection detection
│   ├── models/
│   │   ├── common.py
│   │   ├── projects.py
│   │   ├── governance.py
│   │   ├── scope.py
│   │   ├── people.py
│   │   ├── time_.py
│   │   ├── cost.py
│   │   ├── meetings.py
│   │   └── admin.py
│   ├── repositories/
│   │   ├── protocols.py        # 8 typed Protocols
│   │   ├── base.py
│   │   ├── project_repo.py
│   │   ├── governance_repo.py
│   │   ├── scope_repo.py
│   │   ├── people_repo.py
│   │   ├── time_repo.py
│   │   ├── cost_repo.py
│   │   ├── meeting_repo.py
│   │   └── admin_repo.py
│   ├── services/
│   │   ├── project_service.py
│   │   ├── governance_service.py
│   │   ├── scope_service.py
│   │   ├── people_service.py
│   │   ├── time_service.py
│   │   ├── cost_service.py
│   │   ├── meeting_service.py
│   │   ├── admin_service.py
│   │   └── dashboard_service.py
│   ├── tools/
│   │   ├── base_tool.py        # BaseTool ABC
│   │   ├── project_tool.py
│   │   ├── governance_tool.py
│   │   ├── scope_tool.py
│   │   ├── people_tool.py
│   │   ├── time_tool.py
│   │   ├── cost_tool.py
│   │   ├── meeting_tool.py
│   │   ├── admin_tool.py
│   │   └── dashboard_tool.py
│   ├── registry/
│   │   ├── tool_registry.py
│   │   ├── resource_registry.py
│   │   └── prompt_registry.py
│   ├── server/
│   │   ├── app.py              # FastMCP app + run()
│   │   ├── lifespan.py         # Startup/shutdown
│   │   ├── resources.py        # MCP resources
│   │   ├── prompts.py          # MCP prompts
│   │   └── content/
│   │       ├── api_overview.md
│   │       ├── portfolio_guide.md
│   │       ├── governance_guide.md
│   │       └── scope_guide.md
│   └── telemetry/
│       ├── logging_.py
│       ├── weave_.py
│       └── otel.py
└── tests/
    ├── conftest.py
    ├── unit/
    │   ├── tools/
    │   ├── services/
    │   ├── repositories/
    │   ├── client/
    │   └── guardrails/
    ├── integration/
    └── contract/

Deployment

Docker

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install -e .
CMD ["python", "main.py"]

As MCP Server in Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pm-governance": {
      "command": "python",
      "args": ["/path/to/pm-governance-mcp/main.py"],
      "env": {
        "API_BASE_URL": "https://pm-api.example.com",
        "API_KEY": "sk-xxxx"
      }
    }
  }
}

License

MIT

Support

For issues or questions, refer to ARCHITECTURE.md and openapi.yaml in the repository root.