Skip to main content
Glama
Sign In
design-flow-mcp

design-flow-mcp

by fargo161
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Design Flow MCP

A thin MCP bridge between ChatGPT-compatible MCP clients and Design Flow System v0.2.

The repository also contains a private Custom GPT Action REST API under design_flow_action_api. Both transports call the same adapter and engine; neither owns semantic authority.

The adapter exposes a small capability-based tool surface while all decisions, provenance, TRACE, validation, persistence, and commit boundaries remain inside the Design Flow engine.

What this is

  • A transport and orchestration layer around design-flow-system.

  • Adapter version 0.1.0.

  • Engine version 0.2.0, pinned to merge commit 30bedf2032179fcb46186f30cc86c33b070c17d1.

  • One active Design Flow project/session per server process; multiple project paths may exist below the configured root.

Related MCP server: mcp-kicad-sch-api

What it is not

  • Not the Design Flow semantic engine.

  • Not an LLM provider.

  • Not a database.

  • Not a replacement for the Design Flow CLI.

  • Not a shell, filesystem browser, Python evaluator, or raw-state editor.

Authority boundary

import_draft changes working draft state but creates no decision authority. preview_round is explicitly non-authoritative. Only lock_round can change decision authority, and it calls PersistentProject.lock_draft() rather than editing persistence files. No tool directly edits decisions, concepts, supersession, TRACE, manifests, hashes, or project JSON.

Tools

Read-only tools:

readiness, get_state, get_unresolved, get_round, preview_round, compile_context_handoff, compile_living_document, recommend_next_round, get_decision_ledger, get_concepts, get_trace, and get_session_brief.

Working/session or authority-changing tools:

  • new_project and resume_project create or open a project and engine session.

  • import_draft changes non-authoritative working state.

  • lock_round is the only decision-authority-changing tool.

  • end_session ends the Design Flow session without marking the project complete.

See Tool contracts for preconditions and exact boundaries.

Project-root security

Set DESIGN_FLOW_PROJECT_ROOT to the only directory projects may occupy. Relative paths are resolved below it. Parent traversal, absolute escapes, and detectable symlink escapes are rejected. Draft file imports are subject to the same confinement.

Local setup on Windows PowerShell

cd $HOME\Documents
git clone https://github.com/fargo161/design-flow-mcp.git
cd design-flow-mcp

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

$env:DESIGN_FLOW_PROJECT_ROOT="$HOME\Documents\DesignFlowProjects"
New-Item -ItemType Directory -Force $env:DESIGN_FLOW_PROJECT_ROOT | Out-Null

.\.venv\Scripts\python.exe -m design_flow_mcp.server

The default transport is local stdio, where the MCP client launches this command as a subprocess.

For local Streamable HTTP development:

.\.venv\Scripts\python.exe -m design_flow_mcp.server --transport streamable-http --host 127.0.0.1 --port 8000

The MCP endpoint is http://127.0.0.1:8000/mcp. Streamable HTTP is a deployment surface, not an authentication or tunneling solution. Do not expose it publicly without HTTPS, authentication, network policy, and the MCP SDK's production host/origin configuration.

Development

For an editable local engine checkout, install it first and install this adapter without resolving dependencies:

python -m pip install -e ..\design-flow-system
python -m pip install "mcp>=2,<3" build
python -m pip install -e . --no-deps
python -m unittest discover -s tests -v
python -m build

Normal installation uses the exact Git dependency declared in pyproject.toml; engine source is not copied or vendored here.

Private Custom GPT Action API

$env:DESIGN_FLOW_PROJECT_ROOT="$HOME\Documents\DesignFlowProjects"
$env:DESIGN_FLOW_API_KEY="replace-with-at-least-32-random-characters"
.\.venv\Scripts\python.exe -m design_flow_action_api

The local API is available at http://127.0.0.1:8080/docs. A Custom GPT requires deploying the included Dockerfile behind HTTPS and configuring the X-API-Key Action credential. Project paths remain hidden behind stable opaque IDs.

Supply the API key only through environment or hosting secret management. Do not put secrets in project files or the Docker build context. The REST boundary returns stable sanitized errors and never intentionally exposes physical server paths.

Documents

Available Tools

17 tools
compile_context_handoffA
Read-onlyIdempotent

Read-only. Compile Context Handoff content with the engine compiler. Requires an active project and cannot rewrite semantic state.

Inputs: no named parameters. Returns: object

compile_living_documentA
Read-onlyIdempotent

Read-only. Compile the Living Application Document with the engine renderer. Requires an active project and cannot rewrite semantic state.

Inputs: no named parameters. Returns: object

end_sessionA

Mutating session operation. End the active Design Flow session safely through the engine. It does not mark the project complete or commit a draft.

Inputs: no named parameters. Returns: object

get_conceptsB
Read-onlyIdempotent

Read-only. Return concise current, affected, and historical engine concepts. It exposes no mutation capability.

Inputs: no named parameters. Returns: object

get_decision_ledgerB
Read-onlyIdempotent

Read-only. Return a concise engine decision-ledger view. It exposes no mutation capability.

Inputs: no named parameters. Returns: object

get_roundA
Read-onlyIdempotent

Read-only. Return the active draft summary and latest committed round. Requires an active project and cannot edit either record.

Inputs: no named parameters. Returns: object

get_session_briefA
Read-onlyIdempotent

Read-only. Return the engine session brief and semantic session identity. It does not conflate the MCP connection with the Design Flow session.

Inputs: no named parameters. Returns: object

get_stateA
Read-onlyIdempotent

Read-only. Return concise state compiled by Design Flow. Requires an active project and cannot alter decisions, TRACE, or persistence.

Inputs: no named parameters. Returns: object

get_traceA
Read-onlyIdempotent

Read-only. Return engine-owned TRACE records. No tool can append, edit, or delete TRACE directly.

Inputs: no named parameters. Returns: object

get_unresolvedA
Read-onlyIdempotent

Read-only. Return the engine's canonical unresolved register. Requires an active project and does not reconstruct or change authority.

Inputs: no named parameters. Returns: object

import_draftA

Mutating working-state operation. Import exactly one structured object or allowed-root file through engine draft intake. It does not commit a decision or change semantic authority.

Inputs: draft, draft_file_path. Returns: object

lock_roundA
Destructive

Authority-changing operation. This commits owner-approved draft state through the Design Flow semantic engine and changes authoritative project state. Requires a complete valid draft; failures preserve it.

Inputs: no named parameters. Returns: object

new_projectB

Mutating setup operation. Create a project through the engine and start its Design Flow session. It invents no decisions and creates no decision authority.

Inputs: project_name (required), project_path (required), mode, project_id, +1 more. Returns: object

preview_roundA
Read-onlyIdempotent

Read-only simulation. This is non-authoritative and does not commit any decision. Requires an active draft and uses the engine preview path only.

Inputs: no named parameters. Returns: object

readinessA
Read-onlyIdempotent

Read-only. Report adapter/engine versions, root confinement, and active-project status. Changes no semantic authority.

Inputs: no named parameters. Returns: object

recommend_next_roundA
Read-onlyIdempotent

Read-only advisory operation. Return the engine's bounded recommendation. It is non-authoritative and never starts a round.

Inputs: no named parameters. Returns: object

resume_projectA

Mutating session operation. Validate and open an existing engine project, then resume/start its Design Flow session. It never repairs invalid persisted state.

Inputs: project_path (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools target clearly distinct resources: sessions, drafts, rounds, trace, decisions, concepts, and compiled documents. The main ambiguity is among the many read-only 'get' tools, especially get_state, get_round, and get_session_brief, though their descriptions do provide enough separation for a careful agent.

    Naming Consistency4/5

    The overwhelming majority follow a clear verb_noun pattern such as new_project, resume_project, import_draft, lock_round, and get_trace. 'readiness' is a notable outlier since it is a noun rather than a verb-led command, and get_unresolved is slightly elliptical, but the overall convention is predictable.

    Tool Count4/5

    At 17 tools, the server is slightly above the ideal 3-15 range but still reasonably scoped for a workflow engine with distinct lifecycle, draft, review, and introspection concerns. A few of the read-only getters could potentially be consolidated, but none feel redundant.

    Completeness4/5

    The core Design Flow lifecycle is well covered: project creation/resume/session end, draft import, preview, round locking, recommendations, and multiple read-only views. Obvious gaps include the lack of any explicit discard/abort/cancel operation or project listing/deletion, but the primary workflow appears navigable without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers