Multi-Repo Architecture Hub (oss-mcp)

An extensible Multi-Repo Architecture Router and Model Context Protocol (MCP) server written in Node.js (ESM). Designed for cross-repository dependency discovery, topological routing, and batch AST indexing integration with codebase-memory-mcp.

⚡ Quick Start

1. Prerequisites

Ensure you have Node.js (>= 18) and codebase-memory-mcp installed globally:

# Install codebase-memory-mcp globally
npm install -g codebase-memory-mcp@latest

2. Clone & Install Dependencies

git clone https://github.com/Abbilville/oss-mcp oss-mcp
cd oss-mcp
npm install
npm link # (Optional) links oss-mcp CLI globally

3. Auto-Configure Your AI Agent (Antigravity / Claude / Cursor / Codex)

Run the interactive wizard to automatically inject the MCP server configuration, guidelines, and multi-repo skills into your AI agent:

npm run setup:agent

Installation Scopes:

• Global Scope (Recommended): Registers oss-mcp across all projects on your machine (in ~/.gemini/config/, %APPDATA%\Claude\, ~/.codex/config.json). Every project you open in your AI assistant will immediately have access to oss-mcp without extra per-project configuration.

  npx oss-mcp setup-agent --agent all --global

• Workspace / Local Scope: Injects configuration and skill files (.agents/, .cursor/, CLAUDE.md, CODEX.md) only inside a specific target directory.

  npx oss-mcp setup-agent --agent all --workspace /path/to/your/workspace

Updating & Uninstalling Agents:

• Update Skills & Configs: npm run update:agent or npx oss-mcp update --agent all --global

• Uninstall from Agents: npm run uninstall:agent or npx oss-mcp uninstall --agent all --global

4. Initialize Any Multi-Repo Workspace

Point oss-mcp to your microservices directory. It will scan the repositories, generate registry.yaml, and automatically batch-index the code into AST knowledge graphs:

npx oss-mcp setup /path/to/your/microservices-workspace

Related MCP server: Codebase Contextifier 9000

🚀 Key Capabilities

1. Multi-Project Dynamic Discovery: Resolves repository manifests (registry.yaml) dynamically from CLI parameters, workspace hierarchy, machine catalogs (~/.config/oss-mcp/projects.yaml), or environment variables.

2. Automated Structure & Dependency Scanner: Recursively inspects directory trees across multiple tech stacks (Node.js, Express, React, Python, FastAPI, Java, Go), detecting entry points, ports, and inter-service HTTP/event relationships.

3. Automated Batch AST Indexing: Orchestrates codebase-memory-mcp AST graph indexing across all services in a project manifest with a single command.

4. Structured MCP Interface: Exposes standardized tools for AI agents to query cross-service architectures, trace end-to-end request lifecycles, and navigate multi-service boundaries.

📁 Architecture & Manifest Schema

oss-mcp uses a clean, zero-clutter project structure:

data/
├── projects.yaml.example # Reference template for machine-wide catalog
└── registry.yaml.example # Reference template for repository manifests

1. Workspace Manifest (registry.yaml)

When you run npx oss-mcp setup or npx oss-mcp scan, it creates a registry.yaml at the root of your microservices workspace defining its individual services, metadata, entry points, ports, and relationships.

2. Optional Multi-Project Catalog (~/.config/oss-mcp/projects.yaml)

If you manage multiple distinct microservices projects across your machine, you can optionally register them in ~/.config/oss-mcp/projects.yaml (or via MCP_PROJECTS_CATALOG environment variable). This lets you target any project by ID (e.g. npx oss-mcp index --project ecommerce):

# ~/.config/oss-mcp/projects.yaml
projects:
  ecommerce:
    name: "E-Commerce Microservices"
    description: "Frontend SPA, API Gateway, Auth Service, and Order Service"
    registry_path: "/path/to/ecommerce/registry.yaml"
    root_path: "/path/to/ecommerce/workspace"

  analytics:
    name: "Analytics Platform"
    description: "Event streaming and reporting backend"
    registry_path: "/path/to/analytics/registry.yaml"
    root_path: "/path/to/analytics/workspace"

2. Repository Manifest (registry.yaml)

Each project has a registry.yaml defining its individual services, metadata, entry points, ports, and relationships.

# registry.yaml
repos:
  - name: backend-service
    owner: backend-team
    local_path: ./services/backend-service
    description: "REST API server handling auth, database persistence, and business logic"
    tech_stack:
      - Node.js
      - Express
      - PostgreSQL
      - Redis
      - JWT
    entry_point: src/server.js
    port: 4000

  - name: web-frontend
    owner: frontend-team
    local_path: ./services/web-frontend
    description: "Customer SPA built with React and TypeScript"
    tech_stack:
      - React
      - TypeScript
      - Axios
    entry_point: src/index.tsx
    port: 3000

relationships:
  - source: web-frontend
    target: backend-service
    type: api_call
    description: "Frontend makes REST API calls to backend endpoints for data and authentication."

  - source: web-frontend
    target: backend-service
    type: depends_on
    description: "Frontend depends on backend JWT session management and RBAC permissions."

Supported Relationship Types

• api_call: HTTP / REST / GraphQL invocation from source to target.

• depends_on: Architectural or lifecycle dependency (e.g., shared session, contract dependency).

• event_stream: Asynchronous messaging (Kafka, RabbitMQ, Redis Pub/Sub, AWS EventBridge).

• shared_resource: Shared database schema, cache instance, or storage bucket.

• submodule: Git submodule or monorepo package reference.

🎯 Manifest Resolution Hierarchy

When executing tools or CLI commands, oss-mcp determines which registry to load using a 4-tier fallback:

1. Explicit Flag / Parameter   (--project "ecommerce" or --registry "/path/to/registry.yaml")
   └── 2. Machine Projects Catalog (~/.config/oss-mcp/projects.yaml or MCP_PROJECTS_CATALOG)
       └── 3. Environment Variable   (export MCP_REGISTRY_PATH="/path/to/registry.yaml")
           └── 4. Workspace Traversal (searching current directory & parent folders for registry.yaml)

💻 CLI Reference

🤖 AI Assistant & IDE Integration

oss-mcp provides an architectural bridge that works in tandem with codebase-memory-mcp.

┌─────────────────────────────────────────────────────────────┐
│                       AI Agent Layer                        │
│        (Antigravity / Claude Code / Cursor / Codex)         │
└──────────────────────────────┬──────────────────────────────┘
                               │
               ┌───────────────┴───────────────┐
               ▼                               ▼
 ┌───────────────────────────┐   ┌───────────────────────────┐
 │          oss-mcp          │   │    codebase-memory-mcp    │
 │                           │   │                           │
 │ • Multi-repo discovery    │   │ • Deep AST function index │
 │ • Service topology & port │   │ • Class & symbol search   │
 │ • Cross-repo relationships│   │ • Call graph path tracing │
 │ • Batch index management  │   │ • Source code snippets    │
 └───────────────────────────┘   └───────────────────────────┘

1. Google Antigravity (AGY)

A. Configure MCP Server

Add oss-mcp to your project's .agents/mcp_config.json or globally in ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "oss-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/oss-mcp/src/server.js"]
    }
  }
}

B. Install Workspace Skills & Rules

1. Copy or symlink the .agents/skills/ directory into your active project's .agents/skills/ (or global ~/.gemini/config/skills/).

2. Include the multi-repo routing rule in .agents/AGENTS.md:

   # Multi-Repo Routing
   For any question spanning multiple services or repositories, use the `oss-mcp` MCP server to discover topology with `get_architecture_overview()`, then query `codebase-memory-mcp` scoped to relevant repositories.

C. Antigravity Slash Commands & Usage

Type these commands directly in Antigravity chat:

• /oss setup /path/to/microservices — Auto-scan workspace, infer stacks & ports, generate registry.yaml, and batch-index into AST graphs.

• /oss status — View table of registered services, ports, and graph node/edge counts.

• /oss trace checkout flow from UI to backend — Trace end-to-end cross-service lifecycles with sequence diagrams.

• /oss remove <project_id> — Safely unregister project and purge knowledge graphs.

2. Claude Code (CLI) & Claude Desktop

A. Claude Code CLI Setup

Add the MCP server directly using the claude mcp add command:

# Add oss-mcp MCP server
claude mcp add oss-mcp node /absolute/path/to/oss-mcp/src/server.js

Or add to your project's .claude.json / settings.json:

{
  "mcpServers": {
    "oss-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/oss-mcp/src/server.js"]
    }
  }
}

B. Claude Desktop Setup

Open your Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server definition:

{
  "mcpServers": {
    "oss-mcp": {
      "command": "node",
      "args": ["C:/Telkom/oss-mcp/src/server.js"]
    }
  }
}

C. Claude Workflow Instruction (CLAUDE.md)

Add this guideline to your project's CLAUDE.md to teach Claude how to route multi-repo queries:

## Multi-Repo Architecture Navigation
When answering questions about cross-service interactions, microservices, or APIs:
1. Call `oss-mcp` tool `get_architecture_overview()` to locate caller/callee services and port contracts.
2. Query `codebase-memory-mcp` (`search_graph`, `trace_path`, `get_code_snippet`) scoped by repository name.
3. Synthesize the end-to-end flow with a Mermaid sequence diagram.

D. Example Chat Prompts in Claude

• "Scan the folder ../services and initialize the multi-repo registry."

• "Show all registered microservices and check if their AST graphs are indexed."

• "Trace the JWT authentication flow from frontend login to backend token verification."

3. Cursor IDE

A. Add MCP Server in Cursor

1. Go to Cursor Settings $\rightarrow$ Features $\rightarrow$ MCP.

2. Click + Add New MCP Server.

3. Fill in:

   • Name: oss-mcp

   • Type: command

   • Command: node /absolute/path/to/oss-mcp/src/server.js

4. Click Save and verify the green status dot.

B. Cursor Rules (.cursorrules or .cursor/rules/multi-repo.mdc)

Create a rule file in your workspace:

---
description: Multi-repository architecture navigation rules
globs: *
---
You have access to the `oss-mcp` MCP server.
When the user asks about multi-service architecture or cross-repo communication:
1. Call `get_architecture_overview` to understand service topologies and ports.
2. Trace API calls and dependencies between services.
3. Provide Mermaid sequence diagrams for all cross-service workflows.

C. Example Chat Prompts in Cursor

• @oss-mcp What services communicate with the payment backend?

• @oss-mcp Scan this multi-repo workspace and generate registry.yaml

• How does the frontend client fetch products from the catalog API? Trace the route and handler.

4. OpenAI Codex / Codex CLI

A. Configure MCP Settings

Add oss-mcp to your Codex configuration file (e.g. ~/.codex/config.json or .codex/config.json):

{
  "mcpServers": {
    "oss-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/oss-mcp/src/server.js"]
    }
  }
}

B. Codex Instructions (CODEX.md or .codex/instructions.md)

Add this guideline to your project's CODEX.md to instruct Codex on routing multi-repository queries:

## Multi-Repo Architecture Navigation
When answering questions about cross-service interactions, microservices, or APIs:
1. Call `oss-mcp` tool `get_architecture_overview()` to discover architecture topology and service boundaries.
2. Query `codebase-memory-mcp` (`search_graph`, `trace_path`, `get_code_snippet`) scoped to the relevant repository.
3. Provide end-to-end flow explanations with dependency contracts.

C. Example Chat Prompts in Codex

• "Use get_architecture_overview to inspect dependencies across our microservices."

• "Trace the authentication flow from the frontend client to the auth microservice."

🛠️ Workspace Skills Deep-Dive

Skills in .agents/skills/ encapsulate complete end-to-end multi-repo workflows:

🔌 MCP Tools Reference

License

Distributed under the MIT License.