COS-MCP

Continuity OS — The Operating System for Organizational Continuity

COS-MCP is an MCP (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 — @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

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

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

# 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)

# Dev server for widgets
npm run widgets:dev

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

---

Build Instructions

# 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

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

npm run build

Run with PM2 (recommended)

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

Docker (example 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:

NODE_ENV=production
PORT=3000
GITHUB_TOKEN=ghp_your_token

---

Example Usage

# 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