# PM Governance MCP Server v3

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:**
   ```bash
   pip install -e .
   ```

2. **Configure environment:**
   ```bash
   cp .env.example .env
   # Edit .env with your API credentials
   ```

3. **Run the server:**
   ```bash
   # 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:
```bash
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
```dockerfile
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`:
```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.