ubCode MCP Server

Flow Tool: ubCode MCP Server FLTL_UBCODE_MCP
status: approved
tags: ubflow, installer, mcp
used_by: AGENT_INSTALLER
skills: FLSK_UBFLOW_INST_006, FLSK_UBFLOW_INST_008, FLSK_UBFLOW_003, FLSK_UBFLOW_004, FLSK_UBFLOW_006, FLSK_UBFLOW_005, FLSK_UBFLOW_001

The ubCode MCP server exposes the indexed Sphinx-Needs project via the Model Context Protocol (MCP). Agents query it at the start of every session to retrieve their current instructions and skills, ensuring that agent behavior is always driven by the documented source of truth rather than hardcoded rules.

Usage

Agents connect to the ubCode MCP server and query needs by ID, type, or tag:

# Retrieve the installer agent need and follow its links
get_need(id="AGENT_INSTALLER")
→ follow :applies: links  → load flowinst objects
→ follow :employs: links  → load flowskill objects
→ follow :uses: links     → load flowtool objects

The server is provided by the ubCode VS Code extension and is available as an MCP server in GitHub Copilot agent mode.

Constraints

  • Agents MUST use ubCode MCP as the exclusive interface for reading Sphinx-Needs objects. Direct RST file parsing is not permitted.

  • If the ubCode MCP server is unavailable, the agent MUST detect this and offer to install the ubCode extension from the VS Code Marketplace after explicit user confirmation.

  • The server operates on the last indexed snapshot of the project. Agents should remind the user to re-index after making changes to .rst files.

Missing Capabilities

The following swspec objects describe technical functionality that the ubCode MCP server does not yet implement but is required for ubFlow.

SW Spec: ubFlow magic-word support in MCP server SWSP_UBCODE_001
status: draft
tags: ubflow, mcp, ubcode

The ubCode MCP server SHALL recognise "ubflow" as a reserved keyword when it appears as the value of an agent parameter in any MCP function call (see SWSP_UBCODE_002).

When agent="ubflow" is detected, the server SHALL resolve the instruction and skill needs not from the calling workspace’s ubproject.toml, but from the bundled ubFlow documentation project shipped with the ubCode VS Code extension.

This allows the ubFlow agent stub (a minimal .agent.md in the target repo) to bootstrap itself from extension-internal documentation that is never written into the user’s repository.
SW Spec: Agent parameter for MCP need-query functions SWSP_UBCODE_002
status: draft
tags: ubflow, mcp, ubcode

The MCP functions get_data_for_single_need, query_needs, and get_schema_for_need_filter SHALL accept an optional agent string parameter.

When agent is supplied, the server SHALL switch its lookup context to the documentation project registered for that agent name before executing the query. The caller’s workspace project remains unaffected.

Behaviour:

  • agent omitted → current behaviour (workspace project).

  • agent="ubflow" → resolve from the bundled ubFlow docs (see SWSP_UBCODE_001).

  • agent=<unknown> → return a structured error: {"error": "unknown_agent", "agent": "<value>"}.