Saltar a contenido

Estado de fase (MASTER-00): POC — documentación involucrada en la validación cuantitativa de contexto. Gobernanza: MASTER-00.

Interaction Spec: MCP Context Bundle Extraction Flow

1. Overview & System Goal

Goal

Serve external AI coding agents (Cursor, Claude Code, Copilot) via the Kotlin MCP Server (:docugraph-mcp) JSON-RPC 2.0 tool get_task_context(taskId, maxDepth). Authenticate requests using API keys stored in table: mcp_api_keys, verify RevenueCat subscription entitlements in table: subscriptions, execute reverse topological graph traversal starting from the target task node ID via :docugraph-core, prune unreferenced subtrees, enforce Free tier depth limits (maxDepth = 2), and deliver a minimal Markdown context bundle in under 150ms.

Primary Actors

  • AI Coding Agent: External AI developer CLI or IDE extension (Cursor, Claude Code, Copilot).
  • :docugraph-mcp Server: Kotlin MCP SDK implementation over Stdio or HTTP SSE transport.
  • :docugraph-backend Service (BE-04 mcp.get_task_context): Backend service validating keys and entitlements.
  • :docugraph-core Traversal Engine: KMP graph engine performing reverse topological sorting.
  • PostgreSQL Database: Relational store for table: mcp_api_keys, table: subscriptions, table: nodes, and table: node_edges.

3. State Transition Model

stateDiagram-v2
    [*] --> QueryReceived: AI Agent sends JSON-RPC tools/call (get_task_context)
    QueryReceived --> AuthChecked: Validate X-MCP-API-KEY in table: mcp_api_keys
    AuthChecked --> AuthError: Invalid / Revoked Key (JSON-RPC Error -32001)
    AuthChecked --> EntitlementChecked: Key Valid; Check Subscription Entitlement
    EntitlementChecked --> ReverseTopologicalTraversal: Cap maxDepth=2 if Free Tier; Unlimited if Pro
    ReverseTopologicalTraversal --> BundleAssembled: Prune Unrelated Subtrees & Order Nodes
    BundleAssembled --> ContextDelivered: Return Markdown Bundle (<150ms)

State Matrix Definitions

State Name MCP Transport State Backend Authentication Core Engine Action Output Payload
QueryReceived Transport active (Stdio / SSE); parsing JSON-RPC 2.0. Received X-MCP-API-KEY header. Idle. None.
AuthChecked Transport active; key header extracted. Querying API key hash in table: mcp_api_keys. Idle. None.
AuthError Transport returns JSON-RPC 2.0 Error response. API Key missing, invalid, or revoked. Idle. JSON-RPC Code -32001: "Unauthorized API Key."
EntitlementChecked Transport active; checking subscription claim. User entitlement resolved (free vs pro_tier). Set effectiveMaxDepth = min(requested, allowed). None.
ReverseTopologicalTraversal Transport active; waiting for bundle. Authenticated. :docugraph-core running reverse topological traversal starting from taskId. None.
BundleAssembled Transport active; preparing JSON-RPC response. Authenticated. :docugraph-core completed traversal; Markdown bundle formatted & depth-capped. None (payload queued for transport delivery).
ContextDelivered JSON-RPC 2.0 Success Result returned over transport. Key usage timestamp updated (last_used_at). Traversal complete; bundle generated in <150ms. Formatted Markdown bundle containing pruned node contents.

4. Interaction Sequence & Data Payloads

sequenceDiagram
    autonumber
    actor Agent as AI Agent (Cursor / Claude Code)
    participant MCP as :docugraph-mcp Server
    participant BE as BE-04 (getTaskContext)
    participant DB as DB (mcp_api_keys, subscriptions)
    participant Core as :docugraph-core Engine

    Agent->>MCP: JSON-RPC tools/call { name: "get_task_context", arguments: { taskId: "BE-01", maxDepth: 5 } }
    Note over Agent,MCP: Transport: Stdio or HTTP SSE (X-MCP-API-KEY header)

    MCP->>DB: SELECT * FROM mcp_api_keys WHERE api_key_hash = ? AND is_revoked = false
    alt Invalid / Revoked API Key
        DB-->>MCP: Key record not found or revoked
        MCP-->>Agent: JSON-RPC Error -32001 { code: "UNAUTHORIZED", message: "Invalid or revoked MCP API key." }
    else Valid API Key
        DB-->>MCP: Key Record (user_id: "usr_01H123456789")
        MCP->>DB: SELECT entitlement_id FROM subscriptions WHERE user_id = 'usr_01H123456789'
        DB-->>MCP: entitlement_id = 'free' (or 'pro_tier')

        alt Entitlement == 'free' AND maxDepth > 2
            Note over MCP: Enforce Free Tier Limit: Cap maxDepth = 2, set truncated = true
        end

        MCP->>BE: POST /api/v1/mcp/task-context (operationId: getTaskContext)
        BE->>Core: Execute Reverse Topological Traversal (startNode = 'BE-01', maxDepth = effectiveMaxDepth)
        Core->>Core: Collect BE-01 -> IX-01 -> openapi:loginUser -> table:users -> US-01
        Core->>Core: Prune unrelated nodes (US-02, FE-03, table:projects)
        Core-->>BE: Consolidated Markdown Context String
        BE-->>MCP: 200 OK { context_markdown: "...", node_count: 4, truncated: true }
        MCP-->>Agent: JSON-RPC 2.0 Success Result { content: [{ type: "text", text: "..." }] }
    end

Data Payloads

1. JSON-RPC 2.0 Tool Call Request (get_task_context)

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "tools/call",
  "params": {
    "name": "get_task_context",
    "arguments": {
      "taskId": "BE-01",
      "maxDepth": 5
    }
  }
}

2. Formatted Markdown Context Bundle Response

# Task Context Bundle: BE-01
> Note: Traversal truncated at depth 2 (Free Tier Limit). Upgrade to DocuGraph Pro for unlimited context depth.

---
## [Level 2] US-01: Authentication & Session Management
File: docs/user_stories/US-01_login.md
[Full Markdown Content of US-01]

---
## [Level 1] IX-01: User Authentication Flow
File: docs/interaction/IX-01_login-flow.md
[Full Markdown Content of IX-01]

---
## [Level 1] OpenAPI Operation: loginUser
File: docs/api/openapi.yaml
[Operation contract snippet]

---
## [Level 0] Target Task: BE-01 Auth Login
File: docs/backend/BE-01_auth-login.md
[Full Markdown Content of BE-01]

5. Error Handling Matrix

Error Condition Error Code / Indicator Root Cause System Response Remediation / Recovery
UNAUTHORIZED_KEY JSON-RPC Error -32001 API Key missing, invalid, or revoked. Return JSON-RPC error: "Invalid or revoked MCP API Key." Generate new API key in user account settings.
TASK_NOT_FOUND JSON-RPC Error -32602 Requested task ID (e.g. BE-99) does not exist in workspace. Return error detailing invalid ID and listing valid task IDs. AI agent queries get_dependency_graph for valid task IDs.
DEPTH_TRUNCATED_WARNING Success Result (Header Callout) Free tier user requested maxDepth > 2. Traversal automatically capped at 2; callout inserted at top of bundle. User upgrades to pro_tier for unlimited context depth.
CIRCULAR_DEPENDENCY_DETECTED System Warning Log Cycle encountered during traversal. Traversal engine breaks cycle safely without infinite loops; flags node in audit log. Run validate_traceability to resolve cycle.

6. Traceability Index