Skip to content

Navigation Menu

Sign in
Sign up

Repository files navigation

OrgBrain MCP Server

A reusable Model Context Protocol (MCP) server that provides knowledge-extraction and cross-repo analysis tools for multi-repository organizations. Extract type definitions, user flows, service dependencies, infrastructure configs, and more — then query across your entire codebase.

Features

  • Org-wide analysis: Inventory and analyze many repos across an org; helper script to add all repos from a GitHub org.
  • Cross-repo type mapping: Extract data structures across languages (Rust, TypeScript, Python, Go, Dart) and find shared types between services.
  • Config-driven: Point the server to a YAML file of repos to analyze.
  • Pluggable extractors: Register new extractors in src/extractors/ and wire them via config.
  • Version-aware tools: List refs, aggregate types, user flows, data flow, infra, and diagrams across repos.
  • Knowledge store: Versioned JSON under knowledge/extracted/ with manifests per repo/ref.
  • Infra-aware: Kubernetes and Terraform extractors map infrastructure resources.
  • Journey-aware: Optional journey/impact extractor links journey docs to screens and services.
  • Ready for local dev (pnpm dev) or compiled output (pnpm build && pnpm start).

Quickstart

Requirements: Node.js 18+ and pnpm. For org bootstrap: GitHub CLI (gh) authenticated.

# install deps
pnpm install
# bootstrap config from a GitHub org (requires `gh auth login` first)
pnpm add:org-repos <your-org>
# or manually: copy the example and edit
cp config/example.repos.yaml config/repos.yaml

Once config/repos.yaml exists:

# run in dev mode (watches for changes)
pnpm dev
# or build then run compiled output
pnpm build
pnpm start

Web Dashboard

OrgBrain includes a web dashboard for visualizing and managing knowledge extraction.

Setup

# Install dependencies for server and dashboard
cd server && pnpm install
cd ../dashboard && pnpm install
cd ..

Running

Start both the API server and dashboard:

# Terminal 1: Start API server
cd server
pnpm dev
# Terminal 2: Start dashboard
cd dashboard
pnpm dev

Features

  • Overview - Visual map of all repos with extraction status
  • Diagrams - Interactive Mermaid diagram viewer (C4, flowcharts, sequence)
  • PR Impact - Analyze what breaks if a PR changes types
  • Queries - Search across NIPs, types, user flows, data flow
  • Extraction - Trigger and manage knowledge extractions
  • Type Explorer - Browse types, shared types, and stale dependencies

See server/README.md and dashboard/README.md for more details.

The server reads MCP_CONFIG (defaults to config/repos.yaml).

# override config path if needed
MCP_CONFIG=path/to/custom.yaml pnpm dev

Environment Variables

Variable Default Description
MCP_CONFIG config/repos.yaml Path to configuration file

Using from an MCP client

The server uses stdio transport — MCP clients spawn it as a subprocess.

Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
 "mcpServers": {
 "orgbrain": {
 "command": "node",
 "args": ["/absolute/path/to/orgbrain-mcp-server/dist/index.js"],
 "env": {
 "MCP_CONFIG": "/absolute/path/to/orgbrain-mcp-server/config/repos.yaml"
 }
 }
 }
}

Note: Run pnpm build first to generate dist/index.js. Use absolute paths.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
 "mcpServers": {
 "orgbrain": {
 "command": "node",
 "args": ["/absolute/path/to/orgbrain-mcp-server/dist/index.js"],
 "env": {
 "MCP_CONFIG": "/absolute/path/to/orgbrain-mcp-server/config/repos.yaml"
 }
 }
 }
}

MCP CLI

npx @modelcontextprotocol/cli@latest call \
 --command list_repos \
 --server "node dist/index.js"

Configuration

Copy config/example.repos.yaml to config/repos.yaml and customize.

Global Settings

version: "1.0"
cache_dir: .repo-cache # Where git repos are cloned
knowledge_dir: knowledge/extracted # Where extracted data is stored
# Optional: customize diagram colors by repo type
diagram_styles:
 frontend: "#4CAF50"
 backend: "#FF9800"
 infrastructure: "#607D8B"

Repository Configuration

repositories:
 my-repo:
 # Required fields
 url: https://github.com/org/repo.git # Or git@github.com:org/repo.git
 description: "What this repo does"
 type: frontend # frontend | backend | infrastructure | library | documentation | unknown
 language: typescript
 default_branch: main
 # Optional fields
 enabled: true # Set to false to skip this repo
 private: true # Informational flag
 # What refs to track
 track:
 branches: [main, develop] # Extract these branches
 tags:
 pattern: "v*" # Glob pattern for tags
 latest: 5 # Only extract N most recent matching tags
 # Extractors to run
 extractors:
 - name: extractor_name
 config: { ... } # Extractor-specific config

Extractor Configurations

type_definitions - Data Structures & Cross-Repo Contracts

Extracts structs, classes, interfaces, enums, and type aliases across multiple languages. Enables cross-repo type matching to identify shared data contracts between services.

Supported languages: Rust, TypeScript, Python, Go, Dart, Protobuf

Bonus detection:

  • Zod schemas (TypeScript)
  • ORM models: Django, SQLAlchemy, GORM, TypeORM, Drizzle, Prisma
- name: type_definitions
 config:
 ignore: ["**/generated/**", "**/migrations/**"] # Patterns to skip
 limit: 300 # Max files to process
 includePrivate: true # Include non-public types
 prioritize: ["src/models/", "src/types/"] # Directories to process first

Output includes:

  • Type definitions with fields, variants, generics
  • Relationships (extends, implements, contains, collection)
  • Module groupings for diagram generation
  • Summary statistics by kind/language

user_flows - UI Screens & Navigation

- name: user_flows
 config:
 ignore: ["**/*.test.*", "**/stories/*"] # Glob patterns to skip
 limit: 50 # Max files to process

data_flow - Service Dependencies

- name: data_flow
 # No config options - auto-detects /services/ folders

monorepo - Workspace Structure

- name: monorepo
 # No config options - auto-detects turbo.json, pnpm-workspace.yaml, etc.

kubernetes - K8s Manifests

- name: kubernetes
 config:
 paths: ["k8s/", "manifests/", "deploy/"] # Directories to scan
 resource_types: ["Deployment", "Service", "Ingress"] # Filter by kind

terraform - Infrastructure as Code

- name: terraform
 # No config options - scans all *.tf files

journey_impact - Documentation Mapping

- name: journey_impact
 # No config options - scans docs/, flows/, journey files

nip_usage - Nostr NIP Detection

- name: nip_usage
 config:
 patterns: ["NIP-\\d+", "kind:\\s*\\d+"] # Regex patterns to search
 file_types: ["ts", "js", "rs", "dart", "md"] # File extensions to scan

cloudflare_workers - Cloudflare Workers Projects

Extracts configuration, API endpoints, and infrastructure from Cloudflare Workers projects (Rust/WASM or JavaScript).

- name: cloudflare_workers
 # No config options - auto-detects wrangler.toml

Output includes:

  • Worker name and routes (custom domains)
  • KV namespace bindings
  • Durable Object bindings and class names
  • Queue producers and consumers
  • API endpoints (extracted from Rust router patterns)
  • Rust dependencies from Cargo.toml
  • Compatibility date and build commands

Example Configurations

Backend API with Type Extraction

api-service:
 url: git@github.com:org/api-service.git
 type: backend
 language: rust
 default_branch: main
 track:
 branches: [main]
 tags: { pattern: "v*", latest: 5 }
 extractors:
 - name: type_definitions
 config:
 prioritize: ["src/models/", "src/api/"]
 - name: data_flow
 - name: journey_impact

Frontend App

web-client:
 url: git@github.com:org/web-client.git
 type: frontend
 language: typescript
 default_branch: main
 track:
 branches: [main, develop]
 extractors:
 - name: type_definitions
 - name: user_flows
 - name: data_flow
 - name: journey_impact

Turborepo Monorepo

my-monorepo:
 url: git@github.com:org/my-monorepo.git
 type: frontend
 language: typescript
 default_branch: main
 track:
 branches: [main, develop]
 extractors:
 - name: monorepo
 - name: type_definitions
 - name: user_flows
 config:
 ignore: ["**/node_modules/**", "**/*.test.*"]
 - name: data_flow
 - name: journey_impact

Infrastructure Repo

platform-infra:
 url: git@github.com:org/platform-infra.git
 type: infrastructure
 language: hcl
 default_branch: main
 track:
 branches: [main]
 extractors:
 - name: kubernetes
 config:
 paths: ["k8s/", "argocd/", "helm/"]
 - name: terraform
 - name: journey_impact

Multi-Language Service (with Protobuf)

data-service:
 url: git@github.com:org/data-service.git
 type: backend
 language: go
 default_branch: main
 extractors:
 - name: type_definitions
 config:
 prioritize: ["proto/", "internal/models/"]
 - name: data_flow

Cloudflare Worker (Rust/WASM)

api-gateway:
 url: git@github.com:org/api-gateway.git
 type: backend
 language: rust
 default_branch: main
 extractors:
 - name: cloudflare_workers
 - name: data_flow
 - name: journey_impact

CLI Commands

Knowledge Extraction

# Extract all enabled repos
pnpm build:knowledge
# Extract specific repo
pnpm build:knowledge --repo my-app
# Extract specific ref (branch or tag)
pnpm build:knowledge --repo my-app --ref v1.0.0
# Force re-extraction (ignore cache)
pnpm build:knowledge --force
# List extracted knowledge
pnpm build:knowledge --list
# Remove stale data from disabled/removed repos
pnpm build:knowledge --prune
# Set max age before re-extraction (seconds)
pnpm build:knowledge --max-age 3600

Adding Repos from GitHub Org

# Add all repos from org
pnpm add:org-repos <org-name>
# Interactive mode - select which repos to include
pnpm add:org-repos <org-name> -i
# Start fresh - clear existing config first
pnpm add:org-repos <org-name> --reset
# Specify exact extractors
pnpm add:org-repos <org-name> --extractors user_flows,data_flow,type_definitions
# Use HTTPS URLs instead of SSH
pnpm add:org-repos <org-name> --https
# Include forks and archived repos
pnpm add:org-repos <org-name> --include-forks --include-archived
# Filter repos by name
pnpm add:org-repos <org-name> --filter "^api-"
pnpm add:org-repos <org-name> --exclude "test|demo"
# Preview without saving
pnpm add:org-repos <org-name> --dry-run

Extractor Auto-Selection

When using add:org-repos, extractors are auto-selected based on repo type:

Repo Type Extractors
Frontend monorepo, user_flows, data_flow, journey_impact
Backend monorepo, data_flow, journey_impact
Infrastructure monorepo, kubernetes, terraform, journey_impact
Unknown monorepo, user_flows, data_flow, kubernetes, terraform, journey_impact

Use --extractors for full control over which extractors to enable.

Note: When you disable a repo in config, its extracted data remains until you run --prune. The MCP server automatically filters out disabled repos from query results.

Tools

Tools are registered in src/index.ts from multiple modules:

Query Tools

  • list_repos - List repos with their latest extracted ref
  • list_refs - List branches and tags for each repo (tags sorted by date, branches unsorted)
  • query_nips - Aggregate NIP usage across repos
  • query_flows - Aggregate user flows/screens
  • query_monorepos - Aggregate monorepo structure
  • query_data_flow - Aggregate service dependencies
  • query_infra - Aggregate Kubernetes and Terraform data

Type Analysis Tools

  • query_types - Search type definitions across repos by name, kind, or repo
  • query_shared_types - Find types that appear in multiple repos (identifies shared data contracts)
  • query_type_relationships - Get type relationships within a repo (extends, contains, implements)
  • generate_type_flow_diagram - Generate Mermaid diagram showing cross-repo type flow

Diagram Tools

  • generate_diagram - Generate Mermaid flowchart for repo or ecosystem
  • generate_c4_diagram - Generate C4-style architecture diagrams (context, container, component, dynamic, deployment)
    • detailed: true - Show ALL elements without truncation (default: false)
    • export: true - Include export instructions for saving diagram to file

Extraction Tools

  • extract_ref - Extract a specific ref for a repo
  • extract_all - Extract all enabled repos

Comparison Tools

  • compare_versions - List available versions for comparison
  • diff_versions - Compare extractors between refs

Org Management Tools

  • connect_org - Add repos from a GitHub org
  • disconnect_repo - Remove a repo from config
  • toggle_repo - Enable/disable a repo
  • job_status - Check extraction job status

Diagram Generation Example

# Generate a container diagram for a repo
generate_c4_diagram(repo: "my-app", type: "container")
# Generate a FULL diagram with ALL elements (no truncation)
generate_c4_diagram(repo: "my-app", type: "deployment", detailed: true)
# Generate diagram with export instructions
generate_c4_diagram(repo: "my-app", type: "deployment", detailed: true, export: true)
# Returns: { mermaid: "...", exportTo: { suggestedPath: "docs/diagrams/my-app-deployment.md", instruction: "..." } }
# Ecosystem-wide deployment diagram
generate_c4_diagram(type: "deployment", detailed: true, export: true)
# Available diagram types:
# - context: System context (users, external systems)
# - container: Apps, services, databases
# - component: Internal structure (screens, modules)
# - dynamic: Request/interaction flows with numbered steps
# - deployment: Infrastructure (K8s, Cloudflare Workers, Terraform)

Truncation limits (when detailed: false):

Element Limit
Endpoints 8
Services 5
Screens 8
K8s Deployments 5
Apps per repo (ecosystem) 4

Use detailed: true to show ALL elements without limits.

Cross-Repo Type Analysis Example

# Find shared types between your services
query_shared_types()
# Result shows types appearing in multiple repos:
{
 "sharedTypes": [
 {
 "name": "user",
 "similarity": 85,
 "repos": ["api-service", "web-client", "mobile-app"],
 "instances": [
 { "repo": "api-service", "kind": "struct", "language": "rust" },
 { "repo": "web-client", "kind": "interface", "language": "typescript" },
 { "repo": "mobile-app", "kind": "class", "language": "dart" }
 ]
 }
 ]
}
# Generate a diagram showing type flow between repos
generate_type_flow_diagram()

On-Demand Extraction

The MCP client can trigger extraction directly without running the CLI:

# Extract a specific ref for a repo
extract_ref(repo: "my-app", ref: "v2.0.0")
extract_ref(repo: "my-app", ref: "feature/auth", force: true)
# Extract all enabled repos at their configured branches
extract_all()
extract_all(force: true, repos: ["my-app", "my-backend"])

Results are stored in knowledge/extracted/ and immediately available for queries. Cached data is returned if fresh (<24h) unless force: true.

Diff / Compare Versions

Use compare_versions to see available refs, then diff_versions to compare:

diff_versions(from_ref: "v1.0.0", to_ref: "main")
diff_versions(from_ref: "v1.0.0", to_ref: "v2.0.0", repo: "my-app")
diff_versions(from_ref: "main", to_ref: "develop", extractor: "type_definitions")

Returns:

  • Per-repo diffs: which extractors changed and what was added/removed
  • Aggregated ecosystem diff: types, screens, services, K8s resources across all repos
  • Mermaid diagram: visual representation of the diff

MCP Resources

The server exposes knowledge files as MCP Resources that clients can browse and read directly:

Resource URI Description
knowledge://index Index of all available knowledge
knowledge://extracted/{repo}/{ref}/{extractor} Extracted data (e.g., knowledge://extracted/my-app/branch-main/type_definitions)
knowledge://static/{path} Static knowledge files (markdown, matrices)

Example URIs:

knowledge://index
knowledge://extracted/example-repo/branch-main/type_definitions
knowledge://extracted/example-repo/branch-main/user_flows
knowledge://static/matrices/nip-usage.json

Adding your own extractor

  1. Create a file in src/extractors/ that exports an Extractor and calls registerExtractor (see existing extractors as templates). Implement canExtract (lightweight file check) and extract (do the work, return ExtractionResult).

  2. Import your file in src/extractors/index.ts so it registers at startup.

  3. Add the extractor to any repo in config/repos.yaml under repositories.<name>.extractors, with optional config passed to your extractor.

  4. Run pnpm build:knowledge to generate knowledge; results appear under knowledge/extracted/<repo>/<ref>/your_extractor.json.

Keep extractors fast; use gitManager helpers for file listing/grep at refs, and limit file counts to avoid timeouts.

Project structure

src/
├── index.ts # Server entrypoint
├── lib/
│ ├── config-loader.ts # YAML config loader
│ ├── git-manager.ts # Git helpers (clone/fetch/list/grep)
│ ├── extractor-base.ts # Extractor interface/registry
│ ├── extraction-runner.ts # Orchestrates extractors
│ └── knowledge-store.ts # Versioned knowledge storage
├── extractors/
│ ├── index.ts # Registers all extractors
│ ├── app/ # App-level extractors
│ │ ├── user-flows.ts
│ │ ├── data-flow.ts
│ │ ├── nip-usage.ts
│ │ └── monorepo.ts
│ ├── infra/ # Infrastructure extractors
│ │ ├── kubernetes.ts
│ │ ├── terraform.ts
│ │ └── cloudflare-workers.ts
│ ├── architecture/ # Architecture extractors
│ │ └── journey-impact.ts
│ └── types/ # Type definition extractor
│ ├── index.ts # Main extractor
│ ├── schema.ts # Type definitions & helpers
│ └── parsers/ # Language-specific parsers
│ ├── index.ts # Parser registry
│ ├── rust.ts
│ ├── typescript.ts
│ ├── python.ts
│ ├── go.ts
│ ├── dart.ts
│ ├── protobuf.ts
│ ├── zod.ts # Zod schema detection
│ └── orm.ts # ORM model detection
├── tools/
│ ├── index.ts # Tool aggregator
│ ├── queries.ts # Query tools
│ ├── diagrams.ts # Diagram generation
│ ├── extraction.ts # On-demand extraction
│ ├── comparison.ts # Version comparison
│ ├── org.ts # Org management
│ └── types.ts # Type analysis tools
├── prompts.ts # MCP prompts
└── resources.ts # MCP resources
scripts/
├── build-knowledge.ts # CLI for knowledge extraction
└── add-org-repos.ts # Add repos from GitHub org
config/
├── example.repos.yaml # Sample config
└── repos.yaml # Your config (gitignored)
knowledge/
└── extracted/ # Extracted knowledge (gitignored)
 └── {repo}/
 └── branch-{ref}/
 ├── manifest.json
 ├── type_definitions.json
 ├── user_flows.json
 └── ...

Contributing / Extending

  • Add new tools in src/tools/ and register in src/tools/index.ts.
  • Add new extractors in src/extractors/ and import in src/extractors/index.ts.
  • For the type extractor, add new language parsers in src/extractors/types/parsers/.
  • Keep sample configs free of sensitive data.

License

MIT (see LICENSE).

About

An MCP server that serves up architectural knowledge across a repository in GitHub Org

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

AltStyle によって変換されたページ (->オリジナル) /