Expose flow input/output schemas as MCP Resources and parameter presets as MCP Prompts in `FlowServer`

[dgenio]

Summary

Extend FlowServer beyond Tools to optionally publish each registered flow's input/output JSON Schema as an MCP Resource and curated invocation presets as MCP Prompts, using the FastMCP server already reachable via the fastmcp property.

Why this matters

The MCP specification defines three primitives — Tools, Resources, Prompts — but most servers expose only Tools. Publishing flow schemas as Resources lets MCP clients (and their LLMs) inspect and cache contracts without trial calls, and Prompts give users a discoverable, governed way to invoke a flow with sensible defaults. This is a low-risk differentiation that makes ChainWeaver's governed flows first-class citizens in MCP-native clients.

Current evidence

• chainweaver/mcp/server.py: FlowServer registers flows only as MCP tools (_register_flow, registered_tool_names); the fastmcp property comment explicitly notes it is the hook to "register additional primitives (resources, prompts, raw MCP tools) on the same transport."
• Each flow already has resolvable input/output schemas (Tool.from_flow resolution order referenced in the module docstring), so the Resource payloads exist.
• docs/mcp-server.md documents the Tools-only surface today.

External context

The MCP spec (2025-06-18 and the 2026 RC line) defines Resources and Prompts as standard server capabilities; full JSON Schema 2020-12 tool schemas and content annotations are part of the same surface.

Proposed implementation

1. Add FlowServer(..., expose_schemas: bool = False, expose_prompts: bool = False) (default off to preserve current behavior and governance posture).
2. When expose_schemas, register one Resource per non-excluded flow carrying its input/output schema JSON (respect the same governance filter as tool registration — never expose schemas for filtered flows).
3. When expose_prompts, register a Prompt per flow that templates a documented invocation with default/example inputs derived from the schema.
4. Honor the existing exclusion/governance rules and collision-name handling for the new primitives.

AI-agent execution notes

Inspect chainweaver/mcp/server.py (_register_all_flows, _register_flow, _implicit_exclusion_reason, governance filtering), chainweaver/mcp/_schema.py, docs/mcp-server.md, examples/mcp_flow_server.py, MCP-related tests. Critical: the governance filter that hides flows from the tool surface MUST also hide their Resources/Prompts — add a test asserting no filtered flow leaks via any primitive. Keep mcp/fastmcp an optional extra import (lazy). Do not change default behavior.

Acceptance criteria

• With flags off, FlowServer behavior and registered primitives are unchanged.
• With expose_schemas=True, each non-filtered flow has a discoverable Resource carrying its schema; filtered flows expose nothing.
• With expose_prompts=True, each non-filtered flow has a Prompt that invokes it with valid defaults.
• Governance-filtered flows are absent from tools, resources, and prompts (single regression test covering all three).

Test plan

Unit tests registering a server with both flags and asserting the resource/prompt inventories; governance-leak regression test; serialization of schema resources; example script smoke test.

Documentation plan

docs/mcp-server.md, examples/mcp_flow_server.py, README MCP section, CHANGELOG.

Migration and compatibility notes

Not expected to require migration (additive, default-off).

Risks and tradeoffs

More surface to keep governance-consistent (the leak risk is the main hazard — covered by the mandatory test). Prompts add a small templating concern; keep them schema-derived and deterministic.

Suggested labels

integrations, ecosystem, ai