docs: PRD + ADRs for flow skills and MCP servers#136
Open
rbrasier wants to merge 18 commits into
Open
Conversation
Add planning docs (no code) for two new capabilities: - Upload a SKILL.md to a conversational step (reusable library + inline override), injected as a cache-stable <skills> prompt block. - MCP server integration: admin-registered remote servers, a deterministic `mcp` node, and tool-calling in conversational steps via a separate agentic runner (ILanguageModel unchanged). PRD: flow-skills-and-mcp.prd.md (target v1.52.0 then v1.53.0, MINOR per phase) ADR-031: runtime skills as injected step instructions ADR-032: MCP integration and tool-calling architecture Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GtujrmX4ywLjDUF3j6X2Yh
…2.0) Phase 1 of the Flow Skills & MCP PRD. Flow authors can upload an externally-authored SKILL.md to a library and attach skills to a conversational step; skill bodies are injected into the step's system prompt as a cache-stable <skills> block (ADR-031). - domain: Skill/ParsedSkill/ResolvedSkill entities, ISkillParser + ISkillRepository ports; ConversationalNodeConfig.skillRefs/inlineSkill; BuildSystemPromptInput.resolvedSkills - adapters: dependency-free SkillParser, app_skills table, DrizzleSkillRepository, <skills> prompt block - application: create/update/list/get/archive/restore skill use-cases + ResolveStepSkills - web: skill tRPC router, container wiring, prompt resolution at both call sites, /admin/skills library page, step-editor skill picker MCP/tool-calling (Phase 2) is out of scope; allowedTools is parsed and stored but not yet enforced. Version bump: MINOR (1.51.0 -> 1.52.0; new app_skills table). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GtujrmX4ywLjDUF3j6X2Yh
Foundation for Model Context Protocol integration (ADR-032). Admins can register, manage, and connection-test remote (SSE) MCP servers; the platform discovers their tools. - domain: McpServer/McpTool/McpToolRef entities; IMcpClient, IMcpServerRepository, IMcpServerDirectory ports. Forward-looking config for 2b: 'mcp' FlowNodeType, McpNodeConfig, allowedMcpToolRefs. - adapters: admin_mcp_servers + admin_mcp_tools tables; DrizzleMcpServerRepository; AiSdkMcpClient (experimental_createMCPClient, SSE, env-referenced bearer credential); McpServerDirectory. - application: register/update/list/disable/enable/test server + list-with-tools use-cases. - web: mcpServer tRPC router, container wiring, /admin/mcp-servers page. Flow consumption (deterministic mcp node + conversational tool-loop) is Phase 2b: large runtime/canvas integration gated on the ADR-032 tool-calling spike (live LLM + live MCP server), not runnable in this sandbox. Domain types for it are already in place. Version bump: MINOR (1.52.0 -> 1.53.0; new MCP tables). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GtujrmX4ywLjDUF3j6X2Yh
…se 2b, v1.54.0)
Completes MCP integration (ADR-032): registered servers can now be used
inside flows two ways.
Deterministic mcp node:
- RunMcpNode mirrors RunAutoNode (field resolution, pending execution,
IMcpClient.callTool) and applies the result via the shared
ApplyAutoNodeResult path (persist + advance, ADR-020).
- dispatchMcpNode runs it when a session advances onto an mcp step.
- Full canvas support: node-type picker ("MCP Tool"), McpNode component,
styles/defaults, config modal section (server/tool selectors + fields),
wired through both flow editors; flow router node type enum gains mcp.
Conversational tool-loop:
- ResolveStepTools resolves allowedMcpToolRefs deny-by-default.
- McpToolPrepass runs a non-streaming generateText tool-loop over the
allowed tools and folds gathered results into the step context; the
streaming structured turn is untouched.
- runMcpToolPrepass runs before prompt-building, guarded so failures never
block the turn. Allowed-tools picker added to the conversational editor.
ADR-032 updated: testing strategy (unit-test the deterministic path and
tool selection with fakes; live LLM-over-MCP is a staging smoke test) and
decisions on the former open questions.
Version bump: MINOR (1.53.0 -> 1.54.0; no new tables).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GtujrmX4ywLjDUF3j6X2Yh
The UI merge of main left unresolved conflict markers in VERSION and route.ts and dropped the conversational skills/MCP-tools pickers from node-config-modal.tsx. main also independently shipped its own v1.53.0 (pre-generation evaluation gate), colliding with this branch's MCP work. - Resolve VERSION (1.54.0) and package.json to match; remove markers. - route.ts: keep both runMcpToolPrepass (MCP) and streamGapFollowup (main). - Consolidate MCP work under v1.54.0 (foundation + flow consumption), since main owns v1.53.0; update the implementation summary and phase doc. - Re-add the dropped Skills and MCP-tools pickers to the conversational step editor, using FieldGroupLabel for WCAG label association (main's ESLint 9 flat-config + a11y rules). validate.sh: 15/15 green (typecheck, ESLint 9 lint, tests, version sync, doc lifecycle). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GtujrmX4ywLjDUF3j6X2Yh
QA pass on the merged branch. Added tests closing the gaps in: - skill.ts (73% -> 95%): UpdateSkill (re-parse + version bump, parser-error propagation), RestoreSkill, GetSkill repository-error path. - mcp.ts (90% -> 94%): UpdateMcpServer happy path, ResolveStepTools repository-error propagation. validate.sh: 15/15 green; coverage thresholds pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GtujrmX4ywLjDUF3j6X2Yh
# Conflicts: # VERSION # package.json
… cleanup Gate MCP and Skills behind two Power-User-scoped feature flags (`mcp`, `skills`) using the existing ADR-022 flag-role-scoping, and reshape the flow builder around a cleaner MCP model. - Feature flags: add `mcp` + `skills` to the default-enabled set and the Power-Users seed scoping; gate authoring surfaces via isEnabledForMe. - MCP servers gain a `kind` (context | actions), set at registration. - Context servers are selected flow-wide (Add MCP button + badges beside context docs); the per-node MCP tools section is removed and the tool pre-pass now sources tools from the flow's context servers (legacy per-node refs still honoured). - Action servers run through the MCP node with a human-in-the-loop confirmation gate (default on): reaching the node resolves and parks the tool arguments, and the tool only fires on operator Proceed, reusing the existing awaiting-confirmation park/advance path. - Skills move to a compact icon button + picker modal on the AI instructions field, with selected skills shown as chips. - Admin nav groups Skills, MCP Servers and Knowledge under "Flow Settings". Adds PrepareMcpNode / ConfirmMcpNode / SetFlowContextMcpServers use-cases, a flow `context_mcp_server_ids` column and `admin_mcp_servers.kind` (migration 0027), with unit tests. Version 1.54.0 -> 1.55.0. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01G4ZKgMLCAsR77iqQKPExgq
📊 Playwright E2E ReportView full report with screenshots and traces Run #361 |
Gate the admin sidebar links and page bodies for Skills and MCP Servers on the per-user `mcp`/`skills` flags (isEnabledForMe already folds in role scoping, so this covers both flag-off and not-entitled-by-role). Empty nav groups are dropped, and direct-URL access to the pages shows an unavailable notice instead of the management UI. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01G4ZKgMLCAsR77iqQKPExgq
… page Turn the write (actions-kind) MCP node into a governed agentic action step: the author curates a set of allowed write tools + AI instructions; at runtime the AI picks one tool and generates its arguments from the tool's live schema, the operator can edit every argument in the confirmation card, and the tool fires at most once (a duplicate Proceed is a no-op). - domain: McpNodeConfig.allowedToolNames (toolName/requestFields deprecated, read for back-compat); PendingExecution.toolName. - adapters: McpToolPlanner — propose-only tool selection (strips tool execute so the model returns the call instead of running it); reuses selectAllowedTools. - application: PrepareMcpNode parks the planned call; ConfirmMcpNode claims the execution (idempotency) and runs the operator's edited args; RunMcpNode fires the planned call when confirmation is off. - runtime: dispatchMcpNode plans via the planner then parks/runs; confirmStep threads edited args through to the tool call. - ui: McpConfirmCard renders an editable argument form; node config modal offers a multi-tool allow-list + AI-instructions box (request-field editor removed). - n8n settings extracted to its own /admin/n8n page under Flow Settings; shared connectivity helpers moved to components/admin/connectivity.tsx. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01G4ZKgMLCAsR77iqQKPExgq
…refactor-5xt2w9 # Conflicts: # VERSION # package.json
n8n only powers automated (auto) nodes, so its sidebar entry and page follow the auto_node flag — hidden for users the flag does not entitle, matching the Skills/MCP gating pattern. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01G4ZKgMLCAsR77iqQKPExgq
…refactor-5xt2w9 # Conflicts: # VERSION # apps/web/src/app/api/chat/[sessionId]/stream/route.ts # apps/web/src/components/sidebar.tsx # apps/web/src/lib/container.ts # package.json # packages/adapters/drizzle/meta/0027_snapshot.json # packages/adapters/drizzle/meta/_journal.json
….2.0 This branch's Flow Skills & MCP work is now part of the alpha-2 (2.x.x) release line. Restructure the doc lifecycle around per-alpha folders and renumber this branch's contributions accordingly. - implemented/alpha-1/ ← all historical v0.x/v1.x folders (the 1.x line) - implemented/alpha-2/v2.1.0 ← Flow Skills (was v1.52.0) - implemented/alpha-2/v2.2.0 ← MCP integration + Phase B agentic write node (was v1.54.0 mcp files; split out from main's unrelated bug-fix v1.54.0) - VERSION + package.json → 2.2.0 (MINOR over main's 2.0.0 alpha-2 baseline) Update the skills and guides that move phase docs on completion to the new implemented/alpha-<major>/v<version>/ pattern: build, bugfix, and enhance skills, the versioning guide's lifecycle diagram, and the to-be-implemented README. validate.sh: 15/15 pass (version sync, doc lifecycle, coverage). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01G4ZKgMLCAsR77iqQKPExgq
…E seed) The merge with main resolved the drizzle journal conflict by taking main's side, which listed main's 0027 (usage-budget scopes) and 0028 (scaling) but dropped this branch's own 0027 migration. That left 0027_ancient_black_panther.sql orphaned — not in the journal — so `admin_mcp_servers`, `admin_mcp_tools`, `app_skills`, and the `app_flows.context_mcp_server_ids` column were never created in the E2E database, breaking `db:migrate` parity and the seed flow. Remove the orphaned 0027 and regenerate the additions as 0029_powerful_rhodey onto the tip of main's chain (0028 → 0029). Content is identical (same tables, FKs, indexes, and the flows column); only the sequence number and snapshot change so the migration actually runs. drizzle-kit check: clean. ./validate.sh: 15/15. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01G4ZKgMLCAsR77iqQKPExgq
…pattern The alpha reorganisation (8b5422a) moved every implemented phase doc under implemented/alpha-<major>/v<version>/ but left behind references to the old implemented/v<version>/ layout, which now point at paths that no longer exist. Repoint them at the new pattern: - CONTRIBUTING.md and docs/guides/skills.md — the doc-move convention text - to-be-implemented phase docs — the summary-location instruction and pointers - e2e spec header comments that cite their source phase doc Doc/comment text only; no code changes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GWBJRDN7nWiEUF9FSTkhm8
Bring the v1.58.6 bug-fix diagnosis and implementation summary into the alpha-1 release line to keep the reorganised doc lifecycle complete. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GWBJRDN7nWiEUF9FSTkhm8
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add planning docs (no code) for two new capabilities:
override), injected as a cache-stable prompt block.
mcpnode, and tool-calling in conversational steps via a separateagentic runner (ILanguageModel unchanged).
PRD: flow-skills-and-mcp.prd.md (target v1.52.0 then v1.53.0, MINOR per phase)
ADR-031: runtime skills as injected step instructions
ADR-032: MCP integration and tool-calling architecture
Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01GtujrmX4ywLjDUF3j6X2Yh