Skip to content

Project spec: MCP (never merge) - #5007

Open
jhoffner wants to merge 2 commits into
mainfrom
project/mcp
Open

jhoffner wants to merge 2 commits into
mainfrom
project/mcp

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Never merge, never delete. This PR is the standing project-spec for the Linear project MCP. It stays open for the life of the project and is refreshed only when an epic under it is created, approved or wraps.

As of 2026-11-10 · set at 2681f7d

FSD speaks MCP in two directions, and both should be solid enough to release. As a server, any flow is its own MCP server; that shipped with FIX-22 and has not been tested hard against real clients. As a client, workforce reaches other MCP servers for its workers and coding runs; FIX-2615 is deciding what a connector is and what a project is.

Winning when A flow's MCP server works with several real clients without regressions, with docs that match its behaviour and an example beyond Kitchen Sink. A host installs an MCP server once as a connector, and a worker or coding run uses it with or without a project, while each user's key stays on the server
The read Real clients the flow server is proven against: none recorded. Hosts using a connector with no project: 0, and the teammates lab is first
Now 0 done · 0 in flight · 1 not started · 1 not filed
Kill line If workers get every tool they need through capabilities, and a connector model adds nothing, the client half is mis-shaped. Keep the server half and drop connectors

The territory: FSD as an MCP server and as an MCP client inside the project; which tools a flow exposes, third-party servers, and Linear's Agents API outside it

Above the fence is how FSD speaks MCP. What a given flow exposes over its server, such as workforce's own tools in FIX-2331, belongs to that flow's owner.

The arc has no figure yet: one epic is filed and has not started, and the other lane is a placeholder. It becomes a figure when a second epic is filed.

The epics (live table):

  • FIX-2615 · connectors, and what a project is · not started (Linear: Todo), epic spec in draft
  • FIX-XXX · flow servers proven on real clients · not filed, carries the server scope this project's Linear description already named

Reviewers · look here

  • Whether one project should hold both directions. The original description named client work as optional "if it surfaces"; FIX-2615 is it surfacing.
  • FIX-567 (Linear Agents connector) is filed under this project but is not MCP. The spec says so; moving it is a Linear call.
  • FIX-2331 (Shift Manager project) overlaps FIX-2615. Reconciling it is FIX-2615's call, per its own scope.

Spec · Decisions · Rules · Plan · Prior Linear description, verbatim

How to review this

This is a project-spec: the standing outcome, the cross-epic decisions, and the live state of one Linear project, in four documents. It is not an implementation plan, not any one epic's objective, and not a design.

In scope to challenge:

  • The outcome — is this what the project should be driving at, and would we know if we got there?
  • Whether the project overbuilds. Each epic can earn its place while the whole is too much. That question can only be asked here.
  • A decision in DECISIONS.md that binds several epics, or a rule in BUSINESS-RULES.md with no owner or two.
  • A missing epic the outcome implies, or one listed that does not serve it.

Out of scope — owned by the epic specs below it:

  • Any single epic's objective, issue division, or internals. Those are its epic PR.
  • The figures at the pixel level, and the status in the epics table, which is refreshed as the project moves and is never a review finding.

Feedback in the second list is routed to the epic it concerns, not folded in here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NczDiGthqcWLSoHxXN7UFG

…e mirror replaces it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGthqcWLSoHxXN7UFG
The outcome covers both directions FSD speaks MCP: flows as servers proven on
real clients (placeholder epic), and workforce connectors (FIX-2615).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGthqcWLSoHxXN7UFG
@vercel

vercel Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flow-state-dev-build-site Ready Ready Preview Nov 10, 2026 1:41am UTC
flow-state-dev-docs Ready Ready Preview Nov 10, 2026 1:41am UTC
1 Skipped Deployment
Project Deployment Actions Updated
flow-state-dev-ui Ignored Ignored Preview Nov 10, 2026 1:41am UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-10T01:42:16.979331Z 2681f7d PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass

Verdict: Appropriately scoped. This PR adds only docs under spec/_projects/mcp/ (+231 / −0, 6 files), so there is no code to refactor or consolidate. I found nothing that needs to change before it stays open as the standing spec.

Findings

  1. One claim in DECISIONS.md is slightly narrower than the code.

    • It says each flow serves its endpoint at /api/flows/:kind/mcp.
    • packages/mcp/src/createMcpTransportAdapter.ts:5-6 and :84-90 show that is the default. Callers can opt into a POST /mcp/:kind layout.
    • The binding decision is "one server per flow kind, never one spanning every flow", and that holds either way.
    • Suggestion: say "by default at /api/flows/:kind/mcp", or state the decision without the path. The server-side epic would otherwise inherit a path as if it were locked.
  2. Small overlaps, optional (about 8–12 lines each).

    • The mermaid graph in SPEC.md restates the line under it, "The two epics don't depend on each other".
    • The "not next" list in PLAN.md repeats FIX-2331, FIX-567 and the third-party connectors from "What this project is not" in SPEC.md.
    • Both are cheap to keep and would be cheap to cut. I would not spend a review round on either.

Considered and left alone

  • The near-empty BUSINESS-RULES.md and PLAN.md. The project-spec contract requires the four documents. They say plainly that no rule or card exists yet instead of inventing one.
  • figures/territory.svg and absorbed/linear-content.md. The figure carries the in-scope versus out-of-scope fence that prose does not. The Linear snapshot is a deliberate verbatim record.
  • The kill line. It argues for a smaller outcome (drop connectors if capabilities suffice), which is the right direction.

Architecture notes for the epics below this project

I am recording these here rather than as requests, since the epics own them.

  • Server and client halves share no package today. @flow-state-dev/mcp is the server transport adapter. The client half (FIX-2615) lives in workforce's project-scoped MCP. When FIX-2615 defines "connector", it should say whether the client plumbing stays in workforce or moves to a shared home. Otherwise the two directions will drift on naming and key handling.
  • The "user's key reaches no run, prompt or response" rule binds only FIX-2615 today. If the server epic ever forwards per-user credentials to real clients, that rule moves to BUSINESS-RULES.md with one owner. The current note about promoting it when it binds two epics is the right trigger.

No other changes requested.


Generated by Claude Code

@gitar-bot

gitar-bot Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Code Review ✅ Approved

🟢 Low risk · Adding MCP project-spec documents and a diagram records scope and status without changing executable behavior, so impact is limited to documentation.

Standing project-spec for the MCP Linear project, covering how FSD speaks MCP as a server and as a client, the outcome it targets, and the epics under it. No issues found.

Verification

Rules No rules evaluated

Functional validation Not enabled

Set up

For more verification details, comment gitar display:verbose.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing compact verification results.

Comment with these commands to change the behavior for this request:

Auto-apply Compact
gitar auto-apply:on         
gitar display:verbose         

Was this helpful? React with 👍 / 👎 | Gitar

This branch was successfully deployed

1 active deployment
Preview – flow-state-dev-docs — 2681f7dc Deployed Nov 10, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants