# COS-MCP

**Continuity OS** — The Operating System for Organizational Continuity

COS-MCP is an [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that provides AI-powered organizational continuity planning. It maintains a knowledge graph of employees, systems, projects, and relationships, and exposes tools, resources, and prompts for knowledge graph visualization, risk analysis, employee transition planning, and organizational knowledge base queries.

Built with [NitroStack](https://nitrostack.ai) — `@nitrostack/core` for the MCP server and `@nitrostack/widgets` for UI widgets.

---

## Features

- **Knowledge Graph** — Complete graph of employees, systems, projects, decisions, customers, and their relationships
- **Risk Analysis** — Bus factor calculation, knowledge concentration detection, sole-owner identification
- **Transition Planning** — Composed transition plans, successor scoring, onboarding path generation
- **GitHub Integration** — Repository metadata, contributor analysis, commit/PR history, ownership risk
- **Organizational Knowledge Base** — Decision records (ADRs), meeting summaries, documentation snippets with natural language querying
- **NitroStack Widgets** — Pre-built dashboards and visualizations (Health Dashboard, Ownership Graph, GitHub insights)
- **MCP Prompts** — Structured AI prompts for knowledge transfer summaries, transition reports, health checks, customer handovers

---

## Architecture

```
cos-mcp/
├── src/
│   ├── index.ts                          # Entry point — boots MCP server
│   ├── app.module.ts                     # Root @McpApp + @Module
│   ├── models/index.ts                   # Zod schemas + TypeScript types
│   ├── services/
│   │   ├── mock-data.service.ts          # In-memory data store (employees, projects, systems, graph)
│   │   └── github.service.ts             # GitHub REST API client with caching
│   ├── modules/
│   │   ├── knowledge-graph/              # Org resources, graph tools, knowledge base, prompts
│   │   │   ├── knowledge-graph.module.ts
│   │   │   ├── knowledge-graph.tools.ts   # build_ownership_graph, find_domain_experts, etc.
│   │   │   ├── knowledge-graph.resources.ts # org://employees, org://teams, org://systems, etc.
│   │   │   ├── knowledge-graph.prompts.ts   # knowledge_transfer_summary, transition_report, etc.
│   │   │   └── knowledge-base.ts          # Static ADRs, meeting summaries, docs
│   │   ├── risk/                         # Risk analysis tools
│   │   │   ├── risk.module.ts
│   │   │   └── risk.tools.ts              # analyze_knowledge_risk, calculate_bus_factor
│   │   ├── transition/                   # Transition planning tools
│   │   │   ├── transition.module.ts
│   │   │   └── transition.tools.ts        # generate_transition_plan, recommend_successor, etc.
│   │   └── github/                       # GitHub integration
│   │       ├── github.module.ts
│   │       ├── github.tools.ts            # sync_github_repository, analyze_repository_ownership, etc.
│   │       └── github.resources.ts        # github://repo, github://contributors, github://commits
│   └── widgets/                          # NitroStack widget pages (Next.js static export)
│       ├── app/                          # Page components
│       ├── widget-manifest.json          # Widget registry
│       ├── next.config.mjs
│       └── package.json
└── package.json
```

---

## Module Structure

| Module | Path | Description |
|--------|------|-------------|
| **App** | `src/app.module.ts` | Root module, imports all feature modules |
| **KnowledgeGraph** | `src/modules/knowledge-graph/` | Core module — resources, tools, prompts, knowledge base |
| **Risk** | `src/modules/risk/` | Bus factor and knowledge concentration analysis |
| **Transition** | `src/modules/transition/` | Transition plans, successor recommendations, onboarding |
| **GitHub** | `src/modules/github/` | GitHub REST API integration |

---

## Installation

```bash
# Clone the repository
git clone https://github.com/your-org/cos-mcp.git
cd cos-mcp

# Install dependencies
npm install

# (Optional) Install widget dependencies
cd src/widgets && npm install && cd ../..
```

---

## Environment Variables

Copy `.env.example` to `.env`:

```bash
cp .env.example .env
```

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `NODE_ENV` | No | `development` | Environment (`development`, `production`, `test`) |
| `PORT` | No | `3000` | Port the MCP server listens on |
| `GITHUB_TOKEN` | No | — | GitHub personal access token (5,000 req/hr vs 60 req/hr unauthenticated) |

---

## Running Locally

```bash
# Start the MCP server in dev mode (with hot reload via NitroStudio)
npm run dev

# Or build and run
npm run build
npm start
```

### Widgets (optional)

```bash
# Dev server for widgets
npm run widgets:dev

# Build widgets for production (static export)
npm run widgets:build
```

---

## Build Instructions

```bash
# TypeScript compilation
npm run build

# Build output goes to ./dist/
# Entry point: ./dist/index.js
```

---

## GitHub Integration

COS-MCP integrates with the GitHub REST API to enrich the organizational knowledge graph with live repository data.

### GitHub Tools

| Tool | Description |
|------|-------------|
| `sync_github_repository` | Fetch repository metadata, contributors, commits, PRs, and languages |
| `analyze_repository_ownership` | Calculate bus factor, contribution percentages, ownership risk |
| `enrich_employee_profile` | Merge GitHub commit/PR/ownership data into an employee profile |

### GitHub Resources

| URI | Description |
|-----|-------------|
| `github://repo/{owner}/{repo}` | Repository metadata, contributors, commits, PRs, languages |
| `github://contributors/{owner}/{repo}` | Contributor list with commit counts |
| `github://commits/{owner}/{repo}` | Recent commit history |

### Setup

```bash
export GITHUB_TOKEN=ghp_your_token_here
```

---

## Demo Workflow

### 1. Explore the Organization

```
GET org://employees
GET org://teams
GET org://teams/Payments
GET org://employees/emp_001
```

### 2. Build Ownership Graph

```
Tool: build_ownership_graph
Input: { employeeId: "emp_001" }
```

### 3. Analyze Knowledge Risk

```
Tool: analyze_knowledge_risk
Input: { scope: "organization" }
```

### 4. Find Domain Experts

```
Tool: find_domain_experts
Input: { domain: "payments" }
```

### 5. Identify Hidden Dependencies

```
Tool: identify_hidden_dependencies
Input: { employeeId: "emp_001" }
```

### 6. Query Organizational Knowledge

```
Tool: query_organizational_knowledge
Input: { question: "Why did Alice choose Kafka over RabbitMQ?" }
```

### 7. Recommend Successor

```
Tool: recommend_successor
Input: { roleId: "Senior Engineer", departingEmployeeId: "emp_001" }
```

### 8. Generate Transition Plan

```
Tool: generate_transition_plan
Input: { departingEmployeeId: "emp_001", successorId: "emp_013" }
```

### 9. Use AI Prompts

```
Prompt: knowledge_transfer_summary
Arguments: { employeeId: "emp_001", format: "detailed" }

Prompt: role_transition_report
Arguments: { departingId: "emp_001", successorId: "emp_013" }

Prompt: organizational_health_check
Arguments: { scope: "team", teamId: "Payments" }
```

### 10. Create Onboarding Path

```
Tool: create_onboarding_path
Input: { newEmployeeId: "emp_013", roleId: "Senior Engineer" }
```

---

## MCP Tools

| Tool | Module | Description | Widget |
|------|--------|-------------|--------|
| `build_ownership_graph` | KnowledgeGraph | Build a complete ownership sub-graph for an employee | `ownership-graph` |
| `find_domain_experts` | KnowledgeGraph | Search for domain experts by skills, system ownership, GitHub | — |
| `identify_hidden_dependencies` | KnowledgeGraph | Surface non-obvious responsibilities and hidden dependencies | — |
| `query_organizational_knowledge` | KnowledgeGraph | Natural language query of ADRs, meetings, docs | — |
| `analyze_knowledge_risk` | Risk | Bus factor, sole owners, undocumented systems per team | `health-dashboard` |
| `calculate_bus_factor` | Risk | Bus factor for a specific team | — |
| `generate_transition_plan` | Transition | Composed transition plan (ownership + risk + successor) | — |
| `recommend_successor` | Transition | Score and rank potential successors | — |
| `create_onboarding_path` | Transition | Structured learning path for new hires | — |
| `sync_github_repository` | GitHub | Fetch repository metadata, contributors, commits, PRs | `github-repositories`, `top-contributors`, `commit-activity` |
| `analyze_repository_ownership` | GitHub | Bus factor, contribution %, ownership risk | `repository-bus-factor`, `ownership-percentage`, `critical-repositories` |
| `enrich_employee_profile` | GitHub | Merge GitHub data into employee profile | — |

---

## MCP Resources

| URI | Module | Description |
|-----|--------|-------------|
| `org://employees` | KnowledgeGraph | All employees with roles, teams, skills |
| `org://employees/{employeeId}` | KnowledgeGraph | Employee details with projects, systems, relationships |
| `org://teams` | KnowledgeGraph | All teams with member counts, bus factor, health |
| `org://teams/{teamId}` | KnowledgeGraph | Team breakdown with members, risk, projects, systems |
| `org://systems` | KnowledgeGraph | All systems with ownership, documentation status |
| `org://projects` | KnowledgeGraph | All projects with ownership, contributors, systems |
| `org://knowledge-graph` | KnowledgeGraph | Full knowledge graph (nodes + edges) |
| `github://repo/{owner}/{repo}` | GitHub | Repository metadata, contributors, commits, PRs, languages |
| `github://contributors/{owner}/{repo}` | GitHub | Contributor list with commit counts |
| `github://commits/{owner}/{repo}` | GitHub | Recent commit history |

---

## MCP Prompts

| Prompt | Module | Description |
|--------|--------|-------------|
| `knowledge_transfer_summary` | KnowledgeGraph | KT summary for departing employee |
| `role_transition_report` | KnowledgeGraph | Complete transition report with risk, readiness, timeline |
| `organizational_health_check` | KnowledgeGraph | Org-wide or team health assessment with RAG status |
| `customer_handover_summary` | KnowledgeGraph | Customer relationship handover document |

---

## Widgets

| Widget | Route | Bound Tool |
|--------|-------|------------|
| Organizational Health Dashboard | `/health-dashboard` | `analyze_knowledge_risk` |
| Employee Ownership Graph | `/ownership-graph` | `build_ownership_graph` |
| GitHub Repositories | `/github-repositories` | `sync_github_repository` |
| Top Contributors | `/top-contributors` | `sync_github_repository` |
| Repository Bus Factor | `/repository-bus-factor` | `analyze_repository_ownership` |
| Commit Activity | `/commit-activity` | `sync_github_repository` |
| Ownership Percentage | `/ownership-percentage` | `analyze_repository_ownership` |
| Critical Repositories | `/critical-repositories` | `analyze_repository_ownership` |

---

## Deployment

### Production Build

```bash
npm run build
```

### Run with PM2 (recommended)

```bash
npm install -g pm2
pm2 start dist/index.js --name cos-mcp
```

### Docker (example Dockerfile)

```dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY dist/ ./dist/
CMD ["npm", "start"]
```

### Environment Variables

Ensure these are set in your production environment:

```bash
NODE_ENV=production
PORT=3000
GITHUB_TOKEN=ghp_your_token
```

---

## Example Usage

```bash
# Query all employees
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"resources/read","params":{"uri":"org://employees"},"id":1}'

# Build ownership graph
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"build_ownership_graph","arguments":{"employeeId":"emp_001"}},"id":2}'

# Sync GitHub repository
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"sync_github_repository","arguments":{"owner":"nitrocloudofficial","repo":"nitrostack"}},"id":3}'
```

---

## Organization Data

- **3 teams**: Payments (6 members), Platform (5 members), Growth (3 members)
- **8 projects**: Payment Gateway v3, Platform Migration to EKS, User Onboarding Redesign, Real-Time Fraud Detection, Data Lake Foundation, API Rate Limiter, A/B Testing Platform, PCI DSS Compliance Audit
- **9 systems**: Payment Processor, Ledger Service, API Gateway, Event Bus, User Service, Internal Admin Dashboard, Payment Reconciliation Service, SAP Integration, Vendor X Process
- **12 decision records** (ADR-001 through ADR-012)
- **5 meeting summaries**
- **8 documentation snippets**

---

## License

MIT