Saltar a contenido

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

User Story: MCP Context Bundle Extraction for AI Tasks

User Story Statement

As an AI coding agent (e.g., Cursor, Claude Code, Junie) or software developer driving an agent,
I want to invoke the MCP tool get_task_context specifying a target task ID (BE-XX, FE-XX, IX-XX),
So that I receive a highly focused, pruned Markdown context bundle containing strictly relevant upstream user stories, API contracts (operationId), database tables (table: XXX), and layout specs without token bloat or context window contamination.

Business Rationale & User Impact

Context window overflow is the leading cause of AI agent hallucinations, token waste, and code regressions in complex projects. As defined in AGENTS.md and VISION-00, feeding an entire documentation folder or raw source codebase into an AI prompt degrades task execution quality. By providing a dedicated MCP server tool that executes reverse topological traversal on the dependency DAG (US-03), DocuGraph delivers surgical context bundles that dramatically improve code generation accuracy while lowering token costs.

User Flow & Interaction Overview

  1. AI coding agent receives an assignment to implement a specific task (e.g. BE-01_auth-login.md).
  2. AI agent executes JSON-RPC request to the DocuGraph Kotlin MCP Server (:docugraph-mcp) calling tool get_task_context(taskId = "BE-01", maxDepth = 5).
  3. MCP Server queries :docugraph-core graph engine to perform reverse topological graph traversal starting from node BE-01.
  4. Traversal collects parent User Story (US-01), associated Interaction Spec (IX-01), OpenAPI endpoint definition (operationId: loginUser), and database schema (01_DATABASE_SCHEMA.md table: users).
  5. Traversal prunes all unrelated nodes (e.g. US-02, FE-03, table: projects).
  6. MCP Server compiles collected specifications into a single Markdown context bundle and returns it to the AI agent prompt.

Acceptance Criteria (Gherkin Format)

Scenario 1: Context Bundle Extraction for Target Task

Given a target backend task ID "BE-01" registered in the project dependency DAG
When an AI agent invokes the MCP tool "get_task_context" with parameter `taskId: "BE-01"`
Then the MCP Server performs reverse topological traversal on the project DAG
And returns a Markdown bundle containing the exact contents of upstream story US-01, interaction spec IX-01, operationId loginUser, and table: users
And includes atomic ID headers and cross-reference links for each included node

Scenario 2: Strict Dependency Pruning of Unrelated Subtrees

Given a documentation graph containing multiple distinct subtrees (Authentication, Graph Canvas, Paywall)
When an AI agent requests the context bundle for task "BE-01"
Then the traversal engine excludes all nodes belonging to unrelated subtrees (such as US-03, FE-03, BE-06, table: subscriptions)
And the returned Markdown bundle size is minimal and free of unreferenced specifications

Scenario 3: Freemium Traversal Depth Enforcement

Given a user operating on the Free tier requesting a context bundle with `maxDepth: 5`
When the MCP Server processes the request
Then the traversal algorithm enforces a maximum depth limit of 2 levels (US-06_revenuecat_pro.md)
And appends a notification block to the bundle: "Traversal truncated at depth 2. Upgrade to DocuGraph Pro for unlimited context depth."

Scenario 4: Non-existent Node Error Handling

Given an invalid or non-existent task ID "BE-99"
When an AI agent calls `get_task_context(taskId: "BE-99")`
Then the MCP Server returns a JSON-RPC error response with code -32602 (Invalid Params)
And provides a detailed message listing available valid task IDs in the workspace

Functional Requirements & Constraints

  1. Tool Signature: 
    fun getTaskContext(taskId: String, maxDepth: Int = 5): String
  2. Execution Latency: Topological graph traversal and bundle formatting must complete in under 150 milliseconds for graphs containing up to 1,000 nodes.
  3. Format Standards: Generated Markdown bundles must preserve original node YAML frontmatter blocks and relative file links.

Downstream Atomic Mapping

This User Story serves as the direct upstream source of truth for the following downstream specifications:

  • Interaction Specification: IX-04_mcp-context-bundle-flow.md (IX-04) — JSON-RPC request-response sequence and context bundling flow.
  • Backend Specification: BE-04_mcp-get-task-context.md (BE-04) — Ktor MCP service implementation for POST /api/v1/mcp/task-context.
  • API Contract: openapi.yaml — Single source of truth for REST endpoint with operationId: getTaskContext.
  • MCP Specification: docs/mcp/MCP_SPEC.md (tool: get_task_context) — Comprehensive Kotlin MCP SDK tool definition.

Traceability Index

  • Upstream Dependencies:
  • docs/00_BUSINESS_VISION.md (VISION-00) — Core AI Productivity Rationale.
  • AGENTS.md (AGENTS) — Mandatory AI Agent Protocol.
  • US-03_view_graph.md (US-03) — Dependency DAG Engine.
  • Downstream Direct Linkages (Planned M2/M3):
  • IX-04_mcp-context-bundle-flow.md (IX-04)
  • BE-04_mcp-get-task-context.md (BE-04)
  • tool: get_task_context in docs/mcp/MCP_SPEC.md
  • Related Stories:
  • US-05_validate_traceability.md (US-05) — Graph validation ensuring clean traversals.
  • US-06_revenuecat_pro.md (US-06) — Depth limit entitlement gating.