COMPREHENSIVE ARCHITECTURE PLAN

Auggie SDK → Custom MCP Wrapper → Any Coding Agent

Hybrid Architecture: We use the Auggie SDK as the core context engine while maintaining our custom MCP server for protocol adaptation and orchestration.

Reference: https://docs.augmentcode.com/context-services/sdk/examples

1. High-Level Architecture (Mental Model)

Think in 5 layers, each with one responsibility only.

┌────────────────────────────┐ │ Coding Agents (Clients) │ │ Codex | Claude | Cursor │ └────────────▲───────────────┘ │ MCP (tools) ┌────────────┴───────────────┐ │ MCP Interface Layer │ │ (our custom server.ts) │ └────────────▲───────────────┘ │ internal API ┌────────────┴───────────────┐ │ Context Service Layer │ │ (our serviceClient.ts) │ └────────────▲───────────────┘ │ SDK calls ┌────────────┴───────────────┐ │ Auggie SDK / CLI │ │ (@augmentcode/auggie) │ └────────────▲───────────────┘ │ cloud API ┌────────────┴───────────────┐ │ Auggie Cloud Backend │ │ (embeddings, vectors) │ └────────────────────────────┘

This separation is critical. Never collapse these layers.

2. Layer 1 — Core Context Engine (Auggie SDK)

Purpose

This is the brain. We use the Auggie SDK instead of building from scratch. It knows nothing about MCP, Codex, or Claude.

The Auggie SDK handles: ✅ File ingestion & scanning ✅ Chunking (with language-aware parsing) ✅ Embedding generation (via Auggie cloud API) ✅ Vector storage & management ✅ Semantic retrieval ✅ Metadata management

Our code does NOT need to: ❌ Implement file scanning ❌ Implement chunking algorithms ❌ Manage embeddings or vectors ❌ Set up Qdrant/SQLite storage

Integration Options

Option A: Auggie CLI (current implementation)

• Uses auggie command-line tool
• Simpler setup, works out of the box
• Requires auggie CLI installed globally

Option B: Auggie SDK (programmatic)

• Uses @augmentcode/auggie-sdk npm package
• More control over indexing/search
• DirectContext for explicit file management
• FileSystemContext for automatic directory indexing

SDK Usage Examples

// FileSystemContext - automatic directory indexing import { FileSystemContext } from '@augmentcode/auggie-sdk';

const context = await FileSystemContext.create({ directory: '/path/to/workspace', });

const results = await context.search('authentication logic'); await context.close();

// DirectContext - explicit file control import { DirectContext } from '@augmentcode/auggie-sdk';

const context = await DirectContext.create(); await context.addFiles([ { path: 'src/main.ts', contents: '...' } ]); const results = await context.search('query');

Engine API (clean contract)

Our serviceClient.ts wraps Auggie SDK with this API:

indexWorkspace(): Promise // → auggie index semanticSearch(query, k): Result[] // → auggie search getFile(path): FileContent // → fs.readFileSync getContextForPrompt(query): Bundle // → search + formatting

This API never changes, even if the underlying SDK changes.

3. Layer 2 — Context Service Layer (Orchestration)

Location: src/mcp/serviceClient.ts (✅ IMPLEMENTED)

Purpose

This layer adapts raw retrieval from Auggie SDK into agent-friendly context. This is OUR custom code that adds value on top of the SDK.

Think of it as the “prompt intelligence” layer.

Responsibilities (our custom logic)

✅ Decide how much context to return ✅ Format snippets for agent consumption ✅ Deduplicate results by file path ✅ Enforce token/file limits ✅ Apply heuristics (importance, recency) ✅ Generate context bundles with hints

Must NOT do

❌ Index files (Auggie SDK does this) ❌ Store vectors (Auggie SDK does this) ❌ Talk to agents directly (MCP layer does this)

Context Bundle format (example)

{ "summary": "Data loading pipeline for X", "files": [ { "path": "src/loader.ts", "snippets": [ { "text": "...", "lines": "10-40" } ] } ], "hints": [ "Loader is synchronous", "TODO mentions batching" ] }

This is what prompt enhancement really is.

4. Layer 3 — MCP Interface Layer

Location: src/mcp/server.ts + src/mcp/tools/* (✅ IMPLEMENTED)

Purpose

This is the adapter that lets agents talk to you.

MCP is just a wire protocol. This is OUR custom code that exposes Auggie SDK via MCP.

Responsibilities

✅ Expose tools via MCP protocol ✅ Validate input/output schemas ✅ Map tool calls → service layer ✅ Stay stateless ✅ Format responses for agents

Must NOT do

❌ Business logic (service layer does this) ❌ Retrieval logic (Auggie SDK does this) ❌ Context bundling (service layer does this)

MCP Tools (✅ ALL IMPLEMENTED)

semantic_search(query, top_k) → src/mcp/tools/search.ts get_file(path) → src/mcp/tools/file.ts get_context_for_prompt(query) → src/mcp/tools/context.ts

Only get_context_for_prompt is required for prompt enhancement.

MCP Server Structure (✅ IMPLEMENTED)

src/mcp/ ├── server.ts # MCP server with tool handlers ├── serviceClient.ts # Context service layer └── tools/ ├── search.ts # semantic_search tool ├── file.ts # get_file tool └── context.ts # get_context_for_prompt tool

This layer can be replaced without touching the SDK.

5. Layer 4 — Agent Clients (Codex, Claude, Cursor)

Purpose

Consume context — nothing more.

Agents:

decide when to call tools

decide how to use context

generate final answers

Your system never generates answers.

Why this is correct

Keeps LLM-specific logic out of your engine

Lets you swap agents freely

Avoids prompt coupling

6. Layer 5 — Storage & Index Backend

Location: Auggie Cloud (managed by SDK)

Responsibilities (handled by Auggie SDK)

✅ Persist embeddings in Auggie cloud ✅ Persist metadata ✅ Support fast vector lookup ✅ Handle deduplication

We do NOT need to: ❌ Set up Qdrant or SQLite ❌ Manage vector storage ❌ Handle embedding persistence

Trade-off: Cloud Dependency

The Auggie SDK uses cloud storage for embeddings. This is acceptable because:

• Simplifies deployment (no local DB setup)
• Provides production-grade vector search
• Enables features like searchAndAsk
• Still runs locally (only embeddings API is remote)

Future option: If local-only is critical, could explore local embedding models + Qdrant.

7. Execution Flow (End-to-End)

Indexing (via Auggie SDK)

File system → Auggie CLI/SDK scans files → Auggie chunks content → Auggie API generates embeddings → Auggie cloud stores vectors

Prompt Enhancement (our custom flow)

Agent prompt → MCP tool call (server.ts) → Context Service (serviceClient.ts) → Auggie SDK search → Our context bundling → Formatted response to agent

8. Hybrid Deployment Model

[Our MCP Server + Service Layer] │ Auggie SDK/CLI │ Auggie Cloud API ↓ Codex / Claude / Cursor

Minimal cloud dependency: Only Auggie API for embeddings No exposed ports: Uses stdio transport Code stays local: Only embeddings sent to cloud

9. What Makes This Architecture “Complete”

✅ Clear separation of concerns ✅ Agent-agnostic (works with any MCP client) ✅ LLM-agnostic (no hardcoded prompts) ✅ SDK-based (leverages Auggie infrastructure) ✅ Extensible without rewrites ✅ Hybrid local/cloud approach

This is infrastructure-level design, not a hack.

10. What You Can Safely Add Later

These enhancements can be added without architectural changes:

• File watchers (auto-reindex on changes)
• Incremental indexing (faster updates)
• Multi-repo support (multiple workspaces)
• Role-based filtering (security contexts)
• Hybrid search (keyword + vector)
• Response caching (performance)
• Custom context strategies (pluggable bundling)
• Metrics & monitoring (usage tracking)

11. Implementation Status

✅ Layer 1: Auggie SDK integration (via CLI) ✅ Layer 2: Context Service (serviceClient.ts) ✅ Layer 3: MCP Server (server.ts + tools/) ✅ Layer 4: Agent configuration (Codex CLI) ✅ Layer 5: Storage (Auggie cloud)

Status: FULLY IMPLEMENTED

Final One-Sentence Summary

You are building an agent-agnostic context backend with MCP as the protocol adapter and Auggie SDK as the engine.