GitHub - dugubuyan/agent-nexus: A service-boundary-aware document exchange center for coordinating heterogeneous LLM code agents via MCP. Implements versioned Markdown store, pub-sub notifications, and diff-aware update protocol.

AgentNexus

A service-boundary-aware coordination architecture for heterogeneous LLM code agents.

"Service boundaries, not agent roles, are the appropriate primitive for coordinating LLM agents in real software development."

Overview

Existing multi-agent frameworks (ChatDev, MetaGPT) organize agents around roles within a single simulated organization. AgentNexus takes a different approach: it coordinates agents at the service granularity, matching how real software systems are actually structured.

Each service registers as a sub-project, publishes versioned Markdown documents (requirements, design, API specs, config), and subscribes to documents from services it depends on. When a document changes, subscribers receive a diff-aware notification containing both the structured diff and the full latest content — enabling targeted, context-aware code modifications.

Key Features

• Versioned document store — SHA-256 dedup, full version history, per-service namespacing
• Publish-subscribe notifications — subscribe by exact doc ID or doc type
• Diff-aware updates — get_my_updates_with_context returns unified diff + full content in one call
• Lifecycle stage tracking — explicit design → development → testing → deployment → upgrade per service, with milestone snapshots on transitions
• Service-Driven Agent Onboarding (SDAOP) — generate_instruction_file auto-generates IDE steering files (AGENTS.md, CLAUDE.md, Kiro steering, Cursor rules) for any connecting agent
• MCP HTTP server — streamable-HTTP transport, multiple agents connect simultaneously
• Out-of-band write endpoint — POST /api/documents accepts full content via HTTP body (zero LLM token cost)
• FTS5 full-text search — search_documents with BM25 ranking, phrase/prefix/boolean query support
• Planner AI layer — planner_chat, planner_plan, planner_overview MCP tools + configurable LLM backend
• Web Dashboard — browser-based UI to explore spaces, projects, and documents with full-text search
• AI Chat — built-in chat panel powered by Planner LLM for conversational document Q&A and service planning
• 281 tests — unit + property-based (Hypothesis)

Architecture

┌─────────────────────────────────────────────────────┐
│                  Project Space                       │
│                                                      │
│  ┌──────────────┐    subscribe    ┌───────────────┐  │
│  │ search-      │ ──────────────► │ search-admin- │  │
│  │ service      │                 │ frontend      │  │
│  │              │  notification   │               │  │
│  │ api/v5 ──────┼────────────────►│               │  │
│  └──────────────┘                 └───────────────┘  │
│                                                      │
│              AgentNexus MCP Server                   │
│              http://0.0.0.0:10086/mcp                │
└─────────────────────────────────────────────────────┘

How It Works

When a backend service updates its API document, the frontend agent is automatically notified with a structured diff — no human coordination needed:

Backend Agent              AgentNexus               Frontend Agent
      │                        │                          │
      │── push_document ──────▶│                          │
      │   (api, new version)   │── notification ─────────▶│
      │                        │                          │── get_my_updates_with_context()
      │                        │◀─────────────────────────│
      │                        │── diff + full content ──▶│
      │                        │                          │── apply targeted code changes
      │                        │                          │── ack_update() ────────────▶│
      │                        │                          │

The diff payload looks like:

{
  "doc_id": "backend-service/api",
  "new_version": 5,
  "diff": "@@ -42,6 +42,12 @@\n+## PUT /admin/docs/{doc_id}\n+Update a document in-place...",
  "latest_content": "# API Spec\n\n..."
}

Quick Start

# Install
pip install -e ".[dev]"

# Initialize database
python -m alembic upgrade head

# Start server (default: http://0.0.0.0:10086/mcp)
python src/main.py

Connect from Kiro / any MCP client

{
  "mcpServers": {
    "doc-exchange": {
      "url": "http://localhost:10086/mcp"
    }
  }
}

First steps

# Create a project space
create_space(name="my-project")

# Register a service
register_project(name="backend-api", type="development", project_space_id="<space_id>")

# Push a document
push_document(project_id="<project_id>", doc_id="<project_id>/api", content="# API Spec...")

# Subscribe frontend to backend's API docs
add_subscription(subscriber_project_id="<frontend_id>", project_space_id="<space_id>", target_doc_id="<backend_id>/api")

# Check updates (returns diff + full content)
get_my_updates_with_context(project_id="<frontend_id>")

Web Dashboard

Once the server is running, open http://localhost:10086/ in your browser.

Features:

• Browse — navigate spaces, sub-projects, and documents in a tree view
• Search — full-text search across all documents in a space
• AI Chat — ask questions about your project documents using natural language

LLM configuration: AI Chat requires PLANNER_LLM_API_KEY to be set. Set PLANNER_LLM_PROVIDER (openai or anthropic) and PLANNER_LLM_MODEL as needed. Leave the key unset to disable AI features while keeping all browse/search functionality.

Out-of-Band Write Endpoint

For zero-token document ingestion (bypasses MCP tool-call LLM context), use the HTTP endpoint directly:

curl -X POST http://localhost:10086/api/documents \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project_id>",
    "doc_id": "<project_id>/requirement",
    "content": "# Requirements\n\nContent here..."
  }'

This uses the same DocumentService.push pipeline as push_document (same validation, FTS index update, notifications) but the document content never enters LLM context — making it practical for large documents.

MCP Tools

Configuration

Steering File Integration

Each sub-project's IDE agent uses an onboarding file (steering file, CLAUDE.md, AGENTS.md, etc.) to auto-check for updates at session start. Generate one with:

generate_instruction_file(project_name="my-service", project_space_id="<space_id>", client_type="kiro")

Supported client_type values: kiro, claude, codex, cursor.

This is the Service-Driven Agent Onboarding Protocol (SDAOP) — the MCP service generates the onboarding document itself, so agents require zero manual configuration. See the v3 paper for the formal protocol definition.

Running Tests

python -m pytest tests/ -q

Paper

The accompanying research papers are available in the paper/ directory:

• paper/agentnexus-v3.md — v3 (current): adds SDAOP
• paper/agentnexus.md — v2

dugubuyan. AgentNexus: A Service-Boundary-Aware Coordination Architecture for Heterogeneous LLM Code Agents (v3). Zenodo, 2026. https://doi.org/10.5281/zenodo.20603176

License

MIT