ubCode MCP Server
=================

.. flowtool:: ubCode MCP Server
   :id: FLTL_UBCODE_MCP
   :status: approved
   :tags: ubflow, installer, mcp

   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:

.. code-block:: text

   # 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.

.. swspec:: ubFlow magic-word support in MCP server
   :id: 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.

.. swspec:: Agent parameter for MCP need-query functions
   :id: 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>"}``.