From 644116cc78784ba9f4f4b2f0774f8a0baa916ba3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=CE=B1=CE=B7dr3=CE=B15=20=C9=AE=CE=B1=CE=B7=C9=A6=D6=85l?= =?UTF-8?q?=CA=903=CA=80?= <2878033+a6b8@users.noreply.github.com> Date: Sun, 21 Jun 2026 03:23:03 +0200 Subject: [PATCH 1/2] Docs pivot + reduction + link cleanup #124 Hero/About pivot to schema-format messaging (EN+DE) + Swagger distinction, drop auto-generated aside, reduce nav (FAQ/Use-Cases/References/Ecosystem to .trash), repoint redirects + inbound links, re-sync 57 generated pages, remove stale route-tests. Memo 142. --- astro.config.mjs | 87 +-- .../docs-payload/00-overview.md | 6 +- .../docs-payload/01-schema-format.md | 6 +- .../docs-payload/02-parameters.md | 6 +- .../docs-payload/03-shared-lists.md | 6 +- .../docs-payload/04-output-schema.md | 6 +- .../docs-payload/05-security.md | 6 +- .../spec-generated/docs-payload/06-agents.md | 6 +- .../spec-generated/docs-payload/07-tasks.md | 6 +- .../docs-payload/08-migration.md | 6 +- .../docs-payload/09-validation-rules.md | 6 +- .../spec-generated/docs-payload/10-tests.md | 6 +- .../spec-generated/docs-payload/11-preload.md | 6 +- .../docs-payload/12-prompt-architecture.md | 6 +- .../docs-payload/13-resources.md | 6 +- .../spec-generated/docs-payload/14-skills.md | 6 +- .../spec-generated/docs-payload/15-catalog.md | 6 +- .../docs-payload/16-id-schema.md | 6 +- .../docs-payload/17-selections.md | 6 +- .../spec-generated/docs-payload/18-prefill.md | 6 +- .../docs-payload/19-mcp-integration.md | 6 +- .../docs-payload/20-validation-strategy.md | 6 +- .../docs-payload/21-schema-lifecycle.md | 6 +- .../docs-payload/22-scoring-protocol.md | 6 +- .../docs-payload/23-license-and-tos.md | 6 +- .../docs-payload/best-practice/01-overview.md | 6 +- .../best-practice/10-readable-interface.md | 6 +- .../best-practice/11-reference-data.md | 6 +- .../best-practice/12-load-and-scale.md | 6 +- .../best-practice/13-geo-conventions.md | 6 +- .../best-practice/14-correctness-license.md | 6 +- .../docs-payload/grading/00-overview.md | 6 +- .../grading/01-default-journey.md | 6 +- .../docs-payload/grading/02-eligibility.md | 6 +- .../docs-payload/grading/03-tos.md | 6 +- .../docs-payload/grading/04-phases-single.md | 6 +- .../grading/05-phases-selection.md | 6 +- .../grading/06-determinism-and-tier.md | 6 +- .../grading/07-scoring-vs-grading.md | 6 +- .../docs-payload/grading/08-grading-model.md | 6 +- .../grading/09-security-and-development.md | 6 +- .../grading/10-domain-knowledge.md | 6 +- .../grading/11-about-convention.md | 6 +- .../grading/12-personas-contract.md | 6 +- .../docs-payload/grading/13-skills.md | 6 +- .../grading/14-kanban-data-contract.md | 6 +- .../grading/15-versioning-axes.md | 6 +- .../grading/16-selection-lockfile.md | 6 +- .../grading/17-scope-whitelist.md | 6 +- .../docs-payload/grading/18-flywheel-loop.md | 6 +- .../docs-payload/grading/19-folder-layout.md | 6 +- .../grading/20-entry-point-prompt.md | 6 +- .../docs-payload/grading/21-pre-conditions.md | 6 +- .../grading/22-workbench-island.md | 6 +- .../docs-payload/grading/23-index-json.md | 6 +- .../grading/24-selection-aggregate.md | 6 +- .../grading/25-harness-and-goal.md | 6 +- .../grading/26-monitoring-track.md | 6 +- scripts/sync-spec.mjs | 40 +- src/components/Footer.astro | 4 +- src/components/Hero.astro | 10 +- src/components/SearchCustom.astro | 8 +- src/content/docs/about/faq.md | 81 --- src/content/docs/about/index.mdx | 13 +- .../docs/best-practice/correctness-license.md | 9 +- .../docs/best-practice/geo-conventions.md | 9 +- .../docs/best-practice/load-and-scale.md | 9 +- src/content/docs/best-practice/overview.md | 9 +- .../docs/best-practice/readable-interface.md | 9 +- .../docs/best-practice/reference-data.md | 9 +- src/content/docs/concepts/clients.md | 4 +- src/content/docs/concepts/primitives.md | 4 +- src/content/docs/de/about/faq.md | 81 --- src/content/docs/de/about/index.mdx | 13 +- src/content/docs/de/concepts/clients.md | 4 +- src/content/docs/de/concepts/primitives.md | 4 +- src/content/docs/de/ecosystem/agentprobe.md | 180 ----- src/content/docs/de/ecosystem/x402.mdx | 166 ----- src/content/docs/de/introduction/faq.md | 2 - src/content/docs/de/introduction/use-cases.md | 63 -- src/content/docs/de/quickstart/quickstart.mdx | 12 +- .../docs/de/quickstart/what-is-flowmcp.mdx | 2 +- src/content/docs/de/reference/cli.mdx | 104 --- src/content/docs/de/reference/core-methods.md | 637 ------------------ src/content/docs/de/reference/mcp-server.md | 122 ---- src/content/docs/de/schemas-and-sources.md | 31 - src/content/docs/ecosystem/agentprobe.md | 180 ----- src/content/docs/ecosystem/x402.mdx | 166 ----- src/content/docs/grading/about-convention.md | 9 +- src/content/docs/grading/default-journey.md | 9 +- .../docs/grading/determinism-and-tier.md | 9 +- src/content/docs/grading/domain-knowledge.md | 9 +- src/content/docs/grading/eligibility.md | 9 +- .../docs/grading/entry-point-prompt.md | 9 +- src/content/docs/grading/flywheel-loop.md | 9 +- src/content/docs/grading/folder-layout.md | 9 +- src/content/docs/grading/grading-model.md | 9 +- src/content/docs/grading/harness-and-goal.md | 9 +- src/content/docs/grading/index-json.md | 9 +- .../docs/grading/kanban-data-contract.md | 9 +- src/content/docs/grading/monitoring-track.md | 9 +- src/content/docs/grading/overview.md | 9 +- src/content/docs/grading/personas-contract.md | 9 +- src/content/docs/grading/phases-selection.md | 9 +- src/content/docs/grading/phases-single.md | 9 +- src/content/docs/grading/pre-conditions.md | 9 +- src/content/docs/grading/scope-whitelist.md | 9 +- .../docs/grading/scoring-vs-grading.md | 9 +- .../docs/grading/security-and-development.md | 9 +- .../docs/grading/selection-aggregate.md | 9 +- .../docs/grading/selection-lockfile.md | 9 +- src/content/docs/grading/skills.md | 9 +- src/content/docs/grading/tos.md | 9 +- src/content/docs/grading/versioning-axes.md | 9 +- src/content/docs/grading/workbench-island.md | 9 +- src/content/docs/guides/agent-creation.mdx | 140 ---- src/content/docs/guides/gtfs-pilot.mdx | 172 ----- src/content/docs/guides/hackathon-kit.mdx | 117 ---- src/content/docs/introduction/use-cases.md | 63 -- src/content/docs/quickstart/quickstart.mdx | 12 +- .../docs/quickstart/what-is-flowmcp.mdx | 2 +- src/content/docs/reference/cli.mdx | 121 ---- src/content/docs/reference/core-methods.md | 637 ------------------ src/content/docs/reference/mcp-server.md | 122 ---- src/content/docs/schemas-and-sources.md | 28 - src/content/docs/specification/agents.md | 9 +- src/content/docs/specification/catalog.md | 9 +- src/content/docs/specification/id-schema.md | 9 +- .../docs/specification/license-and-tos.md | 9 +- .../docs/specification/mcp-integration.md | 9 +- src/content/docs/specification/migration.md | 9 +- .../docs/specification/output-schema.md | 9 +- src/content/docs/specification/overview.md | 9 +- src/content/docs/specification/parameters.md | 9 +- src/content/docs/specification/prefill.md | 9 +- src/content/docs/specification/preload.md | 9 +- .../docs/specification/prompt-architecture.md | 9 +- src/content/docs/specification/resources.md | 9 +- src/content/docs/specification/route-tests.md | 231 ------- .../docs/specification/schema-format.md | 9 +- .../docs/specification/schema-lifecycle.md | 9 +- .../docs/specification/scoring-protocol.md | 9 +- src/content/docs/specification/security.md | 9 +- src/content/docs/specification/selections.md | 9 +- .../docs/specification/shared-lists.md | 9 +- src/content/docs/specification/skills.md | 9 +- src/content/docs/specification/tasks.md | 9 +- src/content/docs/specification/tests.md | 9 +- .../docs/specification/validation-rules.md | 9 +- .../docs/specification/validation-strategy.md | 9 +- src/pages/404.astro | 2 +- src/templates/about/faq.template.md | 81 --- src/templates/about/index.template.mdx | 13 +- src/templates/concepts/schemas.template.md | 2 + src/templates/de/about/faq.template.md | 81 --- src/templates/de/about/index.template.mdx | 13 +- src/templates/de/concepts/schemas.template.md | 2 + src/templates/schemas-and-sources.template.md | 28 - 158 files changed, 432 insertions(+), 4308 deletions(-) delete mode 100644 src/content/docs/about/faq.md delete mode 100644 src/content/docs/de/about/faq.md delete mode 100644 src/content/docs/de/ecosystem/agentprobe.md delete mode 100644 src/content/docs/de/ecosystem/x402.mdx delete mode 100644 src/content/docs/de/introduction/use-cases.md delete mode 100644 src/content/docs/de/reference/cli.mdx delete mode 100644 src/content/docs/de/reference/core-methods.md delete mode 100644 src/content/docs/de/reference/mcp-server.md delete mode 100644 src/content/docs/de/schemas-and-sources.md delete mode 100644 src/content/docs/ecosystem/agentprobe.md delete mode 100644 src/content/docs/ecosystem/x402.mdx delete mode 100644 src/content/docs/guides/agent-creation.mdx delete mode 100644 src/content/docs/guides/gtfs-pilot.mdx delete mode 100644 src/content/docs/guides/hackathon-kit.mdx delete mode 100644 src/content/docs/introduction/use-cases.md delete mode 100644 src/content/docs/reference/cli.mdx delete mode 100644 src/content/docs/reference/core-methods.md delete mode 100644 src/content/docs/reference/mcp-server.md delete mode 100644 src/content/docs/schemas-and-sources.md delete mode 100644 src/content/docs/specification/route-tests.md delete mode 100644 src/templates/about/faq.template.md delete mode 100644 src/templates/de/about/faq.template.md delete mode 100644 src/templates/schemas-and-sources.template.md diff --git a/astro.config.mjs b/astro.config.mjs index cfb089c..58f78d8 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -135,23 +135,24 @@ export default defineConfig({ '/concepts/agents-overview/': '/concepts/primitives/', '/de/concepts/agents-overview/': '/de/concepts/primitives/', - '/docs/usage/cli/': '/reference/cli/', - '/docs/usage/mcp-server/': '/reference/mcp-server/', + // Memo 142: Reference section removed; legacy URLs repoint to surviving pages. + '/docs/usage/cli/': '/quickstart/quickstart/', + '/docs/usage/mcp-server/': '/specification/mcp-integration/', '/docs/guides/schema-creation/': '/guides/schema-creation/', '/docs/guides/examples/': '/guides/examples/', '/docs/guides/server-integration/': '/guides/server-integration/', - '/docs/reference/core-methods/': '/reference/core-methods/', - '/docs/reference/cli-reference/': '/reference/cli/', - '/reference/cli-reference/': '/reference/cli/', - '/de/reference/cli-reference/': '/de/reference/cli/', - '/docs/reference/troubleshooting/': '/about/faq/', - '/reference/troubleshooting/': '/about/faq/', - '/de/reference/troubleshooting/': '/de/about/faq/', + '/docs/reference/core-methods/': '/quickstart/quickstart/', + '/docs/reference/cli-reference/': '/quickstart/quickstart/', + '/reference/cli-reference/': '/quickstart/quickstart/', + '/de/reference/cli-reference/': '/de/quickstart/quickstart/', + '/docs/reference/troubleshooting/': '/about/', + '/reference/troubleshooting/': '/about/', + '/de/reference/troubleshooting/': '/de/about/', - '/docs/ecosystem/agentprobe/': '/ecosystem/agentprobe/', - '/docs/ecosystem/x402/': '/ecosystem/x402/', + '/docs/ecosystem/agentprobe/': '/specification/overview/', + '/docs/ecosystem/x402/': '/specification/overview/', '/docs/specification/overview/': '/specification/overview/', '/docs/specification/schema-format/': '/specification/schema-format/', @@ -166,7 +167,7 @@ export default defineConfig({ '/docs/specification/migration/': '/specification/migration/', '/docs/specification/security/': '/specification/security/', '/docs/specification/output-schema/': '/specification/output-schema/', - '/docs/specification/route-tests/': '/specification/route-tests/', + '/docs/specification/route-tests/': '/specification/tests/', '/docs/specification/preload/': '/specification/preload/', '/docs/specification/groups-prompts/': '/specification/groups-prompts/', '/docs/specification/tests/': '/specification/tests/', @@ -181,12 +182,12 @@ export default defineConfig({ '/de/introduction/about/': '/de/about/', '/introduction/why/': '/about/', '/de/introduction/why/': '/de/about/', - '/introduction/faq/': '/about/faq/', - '/de/introduction/faq/': '/de/about/faq/', + '/introduction/faq/': '/about/', + '/de/introduction/faq/': '/de/about/', - // PRD-015: License & ToS FAQ → Schemas & Sources (Memo 060 Phase 4) - '/license-faq/': '/schemas-and-sources/', - '/de/license-faq/': '/de/schemas-and-sources/', + // PRD-015 (Memo 060) → Memo 142: License & ToS FAQ now points to the spec license page. + '/license-faq/': '/specification/license-and-tos/', + '/de/license-faq/': '/de/specification/license-and-tos/', }, integrations: [ starlight({ @@ -243,11 +244,9 @@ export default defineConfig({ translations: { de: 'Ueber FlowMCP' }, collapsed: true, items: [ + // Memo 142 (REMOVE): FAQ, Use Cases, Schemas & Sources moved to + // .trash/memo-142-reduction (default-out reduction principle). { label: 'About FlowMCP', translations: { de: 'Ueber FlowMCP' }, slug: 'about' }, - { label: 'FAQ', translations: { de: 'Haeufige Fragen' }, slug: 'about/faq' }, - { label: 'Use Cases', translations: { de: 'Anwendungsfaelle' }, slug: 'introduction/use-cases' }, - // Memo 060 PRD-016 (LM1): For LLMs verschoben von About-Gruppe nach Get Started. - { label: 'Schemas & Sources', translations: { de: 'Schemas & Quellen' }, slug: 'schemas-and-sources' }, ], }, // Memo 059 PRD-011: Quickstart + Guides merged into "Get Started" (B3/B7). @@ -261,11 +260,9 @@ export default defineConfig({ collapsed: true, items: [ // Memo 060 PRD-016 (QS3): "Quickstart" -> "CLI Setup" (DE bewusst englisch, analog "Tag Search"). + // Memo 142 (REMOVE): Hackathon Kit, Agent Creation, GTFS Pilot -> .trash/memo-142-reduction. { label: 'CLI Setup', translations: { de: 'CLI Setup' }, slug: 'quickstart/quickstart' }, { label: 'For LLMs', translations: { de: 'Fuer LLMs' }, slug: 'introduction/for-llms' }, - { label: 'Hackathon Kit', translations: { de: 'Hackathon-Kit' }, slug: 'guides/hackathon-kit' }, - { label: 'Agent Creation', translations: { de: 'Agent-Erstellung' }, slug: 'guides/agent-creation' }, - { label: 'GTFS Pilot', translations: { de: 'GTFS-Pilot' }, slug: 'guides/gtfs-pilot' }, ], }, // Memo 060 PRD-007 (Phase 2): Concepts reduziert auf 4 Eintraege @@ -293,43 +290,11 @@ export default defineConfig({ ...gradingGroup, // Memo 108: Best Practice nav group (advisory track) + badge. ...bestPracticeGroup, - { - label: 'Reference', - translations: { de: 'Referenz' }, - collapsed: true, - items: [ - { label: 'CLI Usage', translations: { de: 'CLI-Nutzung' }, slug: 'reference/cli' }, - { label: 'Programmatic API', translations: { de: 'Programmatic API' }, slug: 'reference/core-methods' }, - { label: 'MCP Server Mode', translations: { de: 'MCP Server Mode' }, slug: 'reference/mcp-server' }, - ], - }, - { - label: 'Ecosystem', - translations: { de: 'Oekosystem' }, - collapsed: true, - // Memo 064 Phase 4 PRD-011: badge objects replaced by - // parenthesis qualifiers in the label text (no badge styling). - items: [ - { - label: 'AgentProbe (External)', - translations: { de: 'AgentProbe (External)' }, - slug: 'ecosystem/agentprobe', - }, - { - label: 'x402 (Experimental)', - translations: { de: 'x402 (Experimental)' }, - slug: 'ecosystem/x402', - }, - // Memo 064 Phase 4 PRD-011: third ecosystem element. - // geo-gtfs-toolkit has no dedicated ecosystem page yet — - // link to the existing in-site GTFS Pilot guide. - { - label: 'GTFS (Add-on)', - translations: { de: 'GTFS (Add-on)' }, - slug: 'guides/gtfs-pilot', - }, - ], - }, + // Memo 142 (REMOVE): the whole "Reference" (CLI/Programmatic API/MCP + // Server Mode) and "Ecosystem" (AgentProbe/x402/GTFS) nav groups are + // removed; their pages moved to .trash/memo-142-reduction. FlowMCP is a + // format/specification — the add-on/ecosystem surface is the Drumherum, + // not the core message. // Memo 064 Phase 4 PRD-011: lone top-level Blog sidebar entry // removed. Blog has its own /blog/ section (BlogIndexLayout). // Memo 059 PRD-011 (B4/B5): Roadmap + Team removed from sidebar. diff --git a/public/spec-generated/docs-payload/00-overview.md b/public/spec-generated/docs-payload/00-overview.md index a1aa055..9af8ac6 100644 --- a/public/spec-generated/docs-payload/00-overview.md +++ b/public/spec-generated/docs-payload/00-overview.md @@ -6,9 +6,9 @@ spec_file: "00-overview.md" order: 0 section: "Specification" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/00-overview.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/00-overview.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/00-overview.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/00-overview.md." diff --git a/public/spec-generated/docs-payload/01-schema-format.md b/public/spec-generated/docs-payload/01-schema-format.md index 62de99c..50b1197 100644 --- a/public/spec-generated/docs-payload/01-schema-format.md +++ b/public/spec-generated/docs-payload/01-schema-format.md @@ -6,9 +6,9 @@ spec_file: "01-schema-format.md" order: 1 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/01-schema-format.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/01-schema-format.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/01-schema-format.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/01-schema-format.md." diff --git a/public/spec-generated/docs-payload/02-parameters.md b/public/spec-generated/docs-payload/02-parameters.md index 8439133..b3051c9 100644 --- a/public/spec-generated/docs-payload/02-parameters.md +++ b/public/spec-generated/docs-payload/02-parameters.md @@ -6,9 +6,9 @@ spec_file: "02-parameters.md" order: 2 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/02-parameters.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/02-parameters.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/02-parameters.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/02-parameters.md." diff --git a/public/spec-generated/docs-payload/03-shared-lists.md b/public/spec-generated/docs-payload/03-shared-lists.md index 1e729b6..e14de21 100644 --- a/public/spec-generated/docs-payload/03-shared-lists.md +++ b/public/spec-generated/docs-payload/03-shared-lists.md @@ -6,9 +6,9 @@ spec_file: "03-shared-lists.md" order: 3 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/03-shared-lists.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/03-shared-lists.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/03-shared-lists.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/03-shared-lists.md." diff --git a/public/spec-generated/docs-payload/04-output-schema.md b/public/spec-generated/docs-payload/04-output-schema.md index b6f8085..afafa5e 100644 --- a/public/spec-generated/docs-payload/04-output-schema.md +++ b/public/spec-generated/docs-payload/04-output-schema.md @@ -6,9 +6,9 @@ spec_file: "04-output-schema.md" order: 4 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/04-output-schema.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/04-output-schema.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/04-output-schema.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/04-output-schema.md." diff --git a/public/spec-generated/docs-payload/05-security.md b/public/spec-generated/docs-payload/05-security.md index 96f0767..d2d958a 100644 --- a/public/spec-generated/docs-payload/05-security.md +++ b/public/spec-generated/docs-payload/05-security.md @@ -6,9 +6,9 @@ spec_file: "05-security.md" order: 5 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/05-security.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/05-security.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/05-security.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/05-security.md." diff --git a/public/spec-generated/docs-payload/06-agents.md b/public/spec-generated/docs-payload/06-agents.md index b37f99d..f64f59f 100644 --- a/public/spec-generated/docs-payload/06-agents.md +++ b/public/spec-generated/docs-payload/06-agents.md @@ -6,9 +6,9 @@ spec_file: "06-agents.md" order: 6 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/06-agents.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/06-agents.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/06-agents.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/06-agents.md." diff --git a/public/spec-generated/docs-payload/07-tasks.md b/public/spec-generated/docs-payload/07-tasks.md index 0e3b612..037a9b3 100644 --- a/public/spec-generated/docs-payload/07-tasks.md +++ b/public/spec-generated/docs-payload/07-tasks.md @@ -6,9 +6,9 @@ spec_file: "07-tasks.md" order: 7 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/07-tasks.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/07-tasks.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/07-tasks.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/07-tasks.md." diff --git a/public/spec-generated/docs-payload/08-migration.md b/public/spec-generated/docs-payload/08-migration.md index 86d1581..09ea9a8 100644 --- a/public/spec-generated/docs-payload/08-migration.md +++ b/public/spec-generated/docs-payload/08-migration.md @@ -6,9 +6,9 @@ spec_file: "08-migration.md" order: 8 section: "Specification" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/08-migration.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/08-migration.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/08-migration.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/08-migration.md." diff --git a/public/spec-generated/docs-payload/09-validation-rules.md b/public/spec-generated/docs-payload/09-validation-rules.md index 4a5a839..5c537e6 100644 --- a/public/spec-generated/docs-payload/09-validation-rules.md +++ b/public/spec-generated/docs-payload/09-validation-rules.md @@ -6,9 +6,9 @@ spec_file: "09-validation-rules.md" order: 9 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/09-validation-rules.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/09-validation-rules.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/09-validation-rules.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/09-validation-rules.md." diff --git a/public/spec-generated/docs-payload/10-tests.md b/public/spec-generated/docs-payload/10-tests.md index 9d25b8b..548b451 100644 --- a/public/spec-generated/docs-payload/10-tests.md +++ b/public/spec-generated/docs-payload/10-tests.md @@ -6,9 +6,9 @@ spec_file: "10-tests.md" order: 10 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/10-tests.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/10-tests.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/10-tests.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/10-tests.md." diff --git a/public/spec-generated/docs-payload/11-preload.md b/public/spec-generated/docs-payload/11-preload.md index 5eb9948..0bfa9bb 100644 --- a/public/spec-generated/docs-payload/11-preload.md +++ b/public/spec-generated/docs-payload/11-preload.md @@ -6,9 +6,9 @@ spec_file: "11-preload.md" order: 11 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/11-preload.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/11-preload.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/11-preload.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/11-preload.md." diff --git a/public/spec-generated/docs-payload/12-prompt-architecture.md b/public/spec-generated/docs-payload/12-prompt-architecture.md index 7975be7..5398ac2 100644 --- a/public/spec-generated/docs-payload/12-prompt-architecture.md +++ b/public/spec-generated/docs-payload/12-prompt-architecture.md @@ -6,9 +6,9 @@ spec_file: "12-prompt-architecture.md" order: 12 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/12-prompt-architecture.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/12-prompt-architecture.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/12-prompt-architecture.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/12-prompt-architecture.md." diff --git a/public/spec-generated/docs-payload/13-resources.md b/public/spec-generated/docs-payload/13-resources.md index 2d55716..9ad1235 100644 --- a/public/spec-generated/docs-payload/13-resources.md +++ b/public/spec-generated/docs-payload/13-resources.md @@ -6,9 +6,9 @@ spec_file: "13-resources.md" order: 13 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/13-resources.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/13-resources.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/13-resources.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/13-resources.md." diff --git a/public/spec-generated/docs-payload/14-skills.md b/public/spec-generated/docs-payload/14-skills.md index c9e98e1..d93145a 100644 --- a/public/spec-generated/docs-payload/14-skills.md +++ b/public/spec-generated/docs-payload/14-skills.md @@ -6,9 +6,9 @@ spec_file: "14-skills.md" order: 14 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/14-skills.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/14-skills.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/14-skills.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/14-skills.md." diff --git a/public/spec-generated/docs-payload/15-catalog.md b/public/spec-generated/docs-payload/15-catalog.md index db87575..d2f24f9 100644 --- a/public/spec-generated/docs-payload/15-catalog.md +++ b/public/spec-generated/docs-payload/15-catalog.md @@ -6,9 +6,9 @@ spec_file: "15-catalog.md" order: 15 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/15-catalog.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/15-catalog.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/15-catalog.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/15-catalog.md." diff --git a/public/spec-generated/docs-payload/16-id-schema.md b/public/spec-generated/docs-payload/16-id-schema.md index bd64960..bb5228b 100644 --- a/public/spec-generated/docs-payload/16-id-schema.md +++ b/public/spec-generated/docs-payload/16-id-schema.md @@ -6,9 +6,9 @@ spec_file: "16-id-schema.md" order: 16 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/16-id-schema.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/16-id-schema.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/16-id-schema.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/16-id-schema.md." diff --git a/public/spec-generated/docs-payload/17-selections.md b/public/spec-generated/docs-payload/17-selections.md index 9f4c56f..cb81308 100644 --- a/public/spec-generated/docs-payload/17-selections.md +++ b/public/spec-generated/docs-payload/17-selections.md @@ -6,9 +6,9 @@ spec_file: "17-selections.md" order: 17 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/17-selections.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/17-selections.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/17-selections.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/17-selections.md." diff --git a/public/spec-generated/docs-payload/18-prefill.md b/public/spec-generated/docs-payload/18-prefill.md index 58dae7b..ecabac1 100644 --- a/public/spec-generated/docs-payload/18-prefill.md +++ b/public/spec-generated/docs-payload/18-prefill.md @@ -6,9 +6,9 @@ spec_file: "18-prefill.md" order: 18 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/18-prefill.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/18-prefill.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/18-prefill.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/18-prefill.md." diff --git a/public/spec-generated/docs-payload/19-mcp-integration.md b/public/spec-generated/docs-payload/19-mcp-integration.md index 86f65f8..418aee0 100644 --- a/public/spec-generated/docs-payload/19-mcp-integration.md +++ b/public/spec-generated/docs-payload/19-mcp-integration.md @@ -6,9 +6,9 @@ spec_file: "19-mcp-integration.md" order: 19 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/19-mcp-integration.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/19-mcp-integration.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/19-mcp-integration.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/19-mcp-integration.md." diff --git a/public/spec-generated/docs-payload/20-validation-strategy.md b/public/spec-generated/docs-payload/20-validation-strategy.md index 1549b52..3150991 100644 --- a/public/spec-generated/docs-payload/20-validation-strategy.md +++ b/public/spec-generated/docs-payload/20-validation-strategy.md @@ -6,9 +6,9 @@ spec_file: "20-validation-strategy.md" order: 20 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/20-validation-strategy.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/20-validation-strategy.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/20-validation-strategy.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/20-validation-strategy.md." diff --git a/public/spec-generated/docs-payload/21-schema-lifecycle.md b/public/spec-generated/docs-payload/21-schema-lifecycle.md index b5095e4..f7ad799 100644 --- a/public/spec-generated/docs-payload/21-schema-lifecycle.md +++ b/public/spec-generated/docs-payload/21-schema-lifecycle.md @@ -6,9 +6,9 @@ spec_file: "21-schema-lifecycle.md" order: 21 section: "Specification" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/21-schema-lifecycle.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/21-schema-lifecycle.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/21-schema-lifecycle.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/21-schema-lifecycle.md." diff --git a/public/spec-generated/docs-payload/22-scoring-protocol.md b/public/spec-generated/docs-payload/22-scoring-protocol.md index b8ece17..394cb4d 100644 --- a/public/spec-generated/docs-payload/22-scoring-protocol.md +++ b/public/spec-generated/docs-payload/22-scoring-protocol.md @@ -6,9 +6,9 @@ spec_file: "22-scoring-protocol.md" order: 22 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/22-scoring-protocol.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/22-scoring-protocol.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/22-scoring-protocol.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/22-scoring-protocol.md." diff --git a/public/spec-generated/docs-payload/23-license-and-tos.md b/public/spec-generated/docs-payload/23-license-and-tos.md index 07cad10..01ba5c8 100644 --- a/public/spec-generated/docs-payload/23-license-and-tos.md +++ b/public/spec-generated/docs-payload/23-license-and-tos.md @@ -6,9 +6,9 @@ spec_file: "23-license-and-tos.md" order: 23 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/23-license-and-tos.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/23-license-and-tos.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/23-license-and-tos.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/23-license-and-tos.md." diff --git a/public/spec-generated/docs-payload/best-practice/01-overview.md b/public/spec-generated/docs-payload/best-practice/01-overview.md index 73d991b..da7e32d 100644 --- a/public/spec-generated/docs-payload/best-practice/01-overview.md +++ b/public/spec-generated/docs-payload/best-practice/01-overview.md @@ -6,9 +6,9 @@ spec_file: "01-overview.md" order: 1 section: "Best Practice" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/best-practice/0.1.0/01-overview.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/best-practice/0.1.0/01-overview.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "best-practice/0.1.0/01-overview.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: best-practice/0.1.0/01-overview.md." diff --git a/public/spec-generated/docs-payload/best-practice/10-readable-interface.md b/public/spec-generated/docs-payload/best-practice/10-readable-interface.md index 11b31ac..37b5347 100644 --- a/public/spec-generated/docs-payload/best-practice/10-readable-interface.md +++ b/public/spec-generated/docs-payload/best-practice/10-readable-interface.md @@ -6,9 +6,9 @@ spec_file: "10-readable-interface.md" order: 10 section: "Best Practice" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/best-practice/0.1.0/schema-creation/10-readable-interface.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/best-practice/0.1.0/schema-creation/10-readable-interface.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "best-practice/0.1.0/schema-creation/10-readable-interface.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: best-practice/0.1.0/schema-creation/10-readable-interface.md." diff --git a/public/spec-generated/docs-payload/best-practice/11-reference-data.md b/public/spec-generated/docs-payload/best-practice/11-reference-data.md index c4049fb..2cd3aac 100644 --- a/public/spec-generated/docs-payload/best-practice/11-reference-data.md +++ b/public/spec-generated/docs-payload/best-practice/11-reference-data.md @@ -6,9 +6,9 @@ spec_file: "11-reference-data.md" order: 11 section: "Best Practice" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/best-practice/0.1.0/schema-creation/11-reference-data.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/best-practice/0.1.0/schema-creation/11-reference-data.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "best-practice/0.1.0/schema-creation/11-reference-data.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: best-practice/0.1.0/schema-creation/11-reference-data.md." diff --git a/public/spec-generated/docs-payload/best-practice/12-load-and-scale.md b/public/spec-generated/docs-payload/best-practice/12-load-and-scale.md index 6c3f4e6..10f11af 100644 --- a/public/spec-generated/docs-payload/best-practice/12-load-and-scale.md +++ b/public/spec-generated/docs-payload/best-practice/12-load-and-scale.md @@ -6,9 +6,9 @@ spec_file: "12-load-and-scale.md" order: 12 section: "Best Practice" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/best-practice/0.1.0/schema-creation/12-load-and-scale.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/best-practice/0.1.0/schema-creation/12-load-and-scale.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "best-practice/0.1.0/schema-creation/12-load-and-scale.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: best-practice/0.1.0/schema-creation/12-load-and-scale.md." diff --git a/public/spec-generated/docs-payload/best-practice/13-geo-conventions.md b/public/spec-generated/docs-payload/best-practice/13-geo-conventions.md index 8da497d..15b9db2 100644 --- a/public/spec-generated/docs-payload/best-practice/13-geo-conventions.md +++ b/public/spec-generated/docs-payload/best-practice/13-geo-conventions.md @@ -6,9 +6,9 @@ spec_file: "13-geo-conventions.md" order: 13 section: "Best Practice" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/best-practice/0.1.0/schema-creation/13-geo-conventions.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/best-practice/0.1.0/schema-creation/13-geo-conventions.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "best-practice/0.1.0/schema-creation/13-geo-conventions.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: best-practice/0.1.0/schema-creation/13-geo-conventions.md." diff --git a/public/spec-generated/docs-payload/best-practice/14-correctness-license.md b/public/spec-generated/docs-payload/best-practice/14-correctness-license.md index 169b150..ece58f3 100644 --- a/public/spec-generated/docs-payload/best-practice/14-correctness-license.md +++ b/public/spec-generated/docs-payload/best-practice/14-correctness-license.md @@ -6,9 +6,9 @@ spec_file: "14-correctness-license.md" order: 14 section: "Best Practice" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/best-practice/0.1.0/schema-creation/14-correctness-license.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/best-practice/0.1.0/schema-creation/14-correctness-license.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "best-practice/0.1.0/schema-creation/14-correctness-license.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: best-practice/0.1.0/schema-creation/14-correctness-license.md." diff --git a/public/spec-generated/docs-payload/grading/00-overview.md b/public/spec-generated/docs-payload/grading/00-overview.md index e520518..f2cbd37 100644 --- a/public/spec-generated/docs-payload/grading/00-overview.md +++ b/public/spec-generated/docs-payload/grading/00-overview.md @@ -6,9 +6,9 @@ spec_file: "00-overview.md" order: 0 section: "Grading" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/00-overview.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/00-overview.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/00-overview.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/00-overview.md." diff --git a/public/spec-generated/docs-payload/grading/01-default-journey.md b/public/spec-generated/docs-payload/grading/01-default-journey.md index 6e38d50..7b0cbfd 100644 --- a/public/spec-generated/docs-payload/grading/01-default-journey.md +++ b/public/spec-generated/docs-payload/grading/01-default-journey.md @@ -6,9 +6,9 @@ spec_file: "01-default-journey.md" order: 1 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/01-default-journey.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/01-default-journey.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/01-default-journey.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/01-default-journey.md." diff --git a/public/spec-generated/docs-payload/grading/02-eligibility.md b/public/spec-generated/docs-payload/grading/02-eligibility.md index 7341590..4c2111a 100644 --- a/public/spec-generated/docs-payload/grading/02-eligibility.md +++ b/public/spec-generated/docs-payload/grading/02-eligibility.md @@ -6,9 +6,9 @@ spec_file: "02-eligibility.md" order: 2 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/02-eligibility.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/02-eligibility.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/02-eligibility.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/02-eligibility.md." diff --git a/public/spec-generated/docs-payload/grading/03-tos.md b/public/spec-generated/docs-payload/grading/03-tos.md index 69f8016..29f27c8 100644 --- a/public/spec-generated/docs-payload/grading/03-tos.md +++ b/public/spec-generated/docs-payload/grading/03-tos.md @@ -6,9 +6,9 @@ spec_file: "03-tos.md" order: 3 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/03-tos.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/03-tos.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/03-tos.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/03-tos.md." diff --git a/public/spec-generated/docs-payload/grading/04-phases-single.md b/public/spec-generated/docs-payload/grading/04-phases-single.md index d454c67..5632706 100644 --- a/public/spec-generated/docs-payload/grading/04-phases-single.md +++ b/public/spec-generated/docs-payload/grading/04-phases-single.md @@ -6,9 +6,9 @@ spec_file: "04-phases-single.md" order: 4 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/04-phases-single.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/04-phases-single.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/04-phases-single.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/04-phases-single.md." diff --git a/public/spec-generated/docs-payload/grading/05-phases-selection.md b/public/spec-generated/docs-payload/grading/05-phases-selection.md index 2b36172..73ab2f3 100644 --- a/public/spec-generated/docs-payload/grading/05-phases-selection.md +++ b/public/spec-generated/docs-payload/grading/05-phases-selection.md @@ -6,9 +6,9 @@ spec_file: "05-phases-selection.md" order: 5 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/05-phases-selection.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/05-phases-selection.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/05-phases-selection.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/05-phases-selection.md." diff --git a/public/spec-generated/docs-payload/grading/06-determinism-and-tier.md b/public/spec-generated/docs-payload/grading/06-determinism-and-tier.md index 38e3f18..4f5e0ea 100644 --- a/public/spec-generated/docs-payload/grading/06-determinism-and-tier.md +++ b/public/spec-generated/docs-payload/grading/06-determinism-and-tier.md @@ -6,9 +6,9 @@ spec_file: "06-determinism-and-tier.md" order: 6 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/06-determinism-and-tier.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/06-determinism-and-tier.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/06-determinism-and-tier.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/06-determinism-and-tier.md." diff --git a/public/spec-generated/docs-payload/grading/07-scoring-vs-grading.md b/public/spec-generated/docs-payload/grading/07-scoring-vs-grading.md index ad4ceb9..dd97b83 100644 --- a/public/spec-generated/docs-payload/grading/07-scoring-vs-grading.md +++ b/public/spec-generated/docs-payload/grading/07-scoring-vs-grading.md @@ -6,9 +6,9 @@ spec_file: "07-scoring-vs-grading.md" order: 7 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/07-scoring-vs-grading.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/07-scoring-vs-grading.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/07-scoring-vs-grading.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/07-scoring-vs-grading.md." diff --git a/public/spec-generated/docs-payload/grading/08-grading-model.md b/public/spec-generated/docs-payload/grading/08-grading-model.md index 832d835..191d825 100644 --- a/public/spec-generated/docs-payload/grading/08-grading-model.md +++ b/public/spec-generated/docs-payload/grading/08-grading-model.md @@ -6,9 +6,9 @@ spec_file: "08-grading-model.md" order: 8 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/08-grading-model.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/08-grading-model.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/08-grading-model.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/08-grading-model.md." diff --git a/public/spec-generated/docs-payload/grading/09-security-and-development.md b/public/spec-generated/docs-payload/grading/09-security-and-development.md index bae8343..85cbba2 100644 --- a/public/spec-generated/docs-payload/grading/09-security-and-development.md +++ b/public/spec-generated/docs-payload/grading/09-security-and-development.md @@ -6,9 +6,9 @@ spec_file: "09-security-and-development.md" order: 9 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/09-security-and-development.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/09-security-and-development.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/09-security-and-development.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/09-security-and-development.md." diff --git a/public/spec-generated/docs-payload/grading/10-domain-knowledge.md b/public/spec-generated/docs-payload/grading/10-domain-knowledge.md index a43cd76..92c0a22 100644 --- a/public/spec-generated/docs-payload/grading/10-domain-knowledge.md +++ b/public/spec-generated/docs-payload/grading/10-domain-knowledge.md @@ -6,9 +6,9 @@ spec_file: "10-domain-knowledge.md" order: 10 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/10-domain-knowledge.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/10-domain-knowledge.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/10-domain-knowledge.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/10-domain-knowledge.md." diff --git a/public/spec-generated/docs-payload/grading/11-about-convention.md b/public/spec-generated/docs-payload/grading/11-about-convention.md index c50cfea..40c5e43 100644 --- a/public/spec-generated/docs-payload/grading/11-about-convention.md +++ b/public/spec-generated/docs-payload/grading/11-about-convention.md @@ -6,9 +6,9 @@ spec_file: "11-about-convention.md" order: 11 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/11-about-convention.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/11-about-convention.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/11-about-convention.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/11-about-convention.md." diff --git a/public/spec-generated/docs-payload/grading/12-personas-contract.md b/public/spec-generated/docs-payload/grading/12-personas-contract.md index 024f1b3..f895659 100644 --- a/public/spec-generated/docs-payload/grading/12-personas-contract.md +++ b/public/spec-generated/docs-payload/grading/12-personas-contract.md @@ -6,9 +6,9 @@ spec_file: "12-personas-contract.md" order: 12 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/12-personas-contract.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/12-personas-contract.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/12-personas-contract.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/12-personas-contract.md." diff --git a/public/spec-generated/docs-payload/grading/13-skills.md b/public/spec-generated/docs-payload/grading/13-skills.md index 2e1e97e..2727447 100644 --- a/public/spec-generated/docs-payload/grading/13-skills.md +++ b/public/spec-generated/docs-payload/grading/13-skills.md @@ -6,9 +6,9 @@ spec_file: "13-skills.md" order: 13 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/13-skills.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/13-skills.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/13-skills.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/13-skills.md." diff --git a/public/spec-generated/docs-payload/grading/14-kanban-data-contract.md b/public/spec-generated/docs-payload/grading/14-kanban-data-contract.md index 62a8e88..faa4087 100644 --- a/public/spec-generated/docs-payload/grading/14-kanban-data-contract.md +++ b/public/spec-generated/docs-payload/grading/14-kanban-data-contract.md @@ -6,9 +6,9 @@ spec_file: "14-kanban-data-contract.md" order: 14 section: "Grading" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/14-kanban-data-contract.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/14-kanban-data-contract.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/14-kanban-data-contract.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/14-kanban-data-contract.md." diff --git a/public/spec-generated/docs-payload/grading/15-versioning-axes.md b/public/spec-generated/docs-payload/grading/15-versioning-axes.md index 1e393de..f960378 100644 --- a/public/spec-generated/docs-payload/grading/15-versioning-axes.md +++ b/public/spec-generated/docs-payload/grading/15-versioning-axes.md @@ -6,9 +6,9 @@ spec_file: "15-versioning-axes.md" order: 15 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/15-versioning-axes.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/15-versioning-axes.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/15-versioning-axes.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/15-versioning-axes.md." diff --git a/public/spec-generated/docs-payload/grading/16-selection-lockfile.md b/public/spec-generated/docs-payload/grading/16-selection-lockfile.md index e7dfcc4..c10b2b5 100644 --- a/public/spec-generated/docs-payload/grading/16-selection-lockfile.md +++ b/public/spec-generated/docs-payload/grading/16-selection-lockfile.md @@ -6,9 +6,9 @@ spec_file: "16-selection-lockfile.md" order: 16 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/16-selection-lockfile.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/16-selection-lockfile.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/16-selection-lockfile.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/16-selection-lockfile.md." diff --git a/public/spec-generated/docs-payload/grading/17-scope-whitelist.md b/public/spec-generated/docs-payload/grading/17-scope-whitelist.md index a519cff..81872b9 100644 --- a/public/spec-generated/docs-payload/grading/17-scope-whitelist.md +++ b/public/spec-generated/docs-payload/grading/17-scope-whitelist.md @@ -6,9 +6,9 @@ spec_file: "17-scope-whitelist.md" order: 17 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/17-scope-whitelist.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/17-scope-whitelist.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/17-scope-whitelist.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/17-scope-whitelist.md." diff --git a/public/spec-generated/docs-payload/grading/18-flywheel-loop.md b/public/spec-generated/docs-payload/grading/18-flywheel-loop.md index bf35d66..c52d248 100644 --- a/public/spec-generated/docs-payload/grading/18-flywheel-loop.md +++ b/public/spec-generated/docs-payload/grading/18-flywheel-loop.md @@ -6,9 +6,9 @@ spec_file: "18-flywheel-loop.md" order: 18 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/18-flywheel-loop.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/18-flywheel-loop.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/18-flywheel-loop.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/18-flywheel-loop.md." diff --git a/public/spec-generated/docs-payload/grading/19-folder-layout.md b/public/spec-generated/docs-payload/grading/19-folder-layout.md index dfe983f..7715fa0 100644 --- a/public/spec-generated/docs-payload/grading/19-folder-layout.md +++ b/public/spec-generated/docs-payload/grading/19-folder-layout.md @@ -6,9 +6,9 @@ spec_file: "19-folder-layout.md" order: 19 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/19-folder-layout.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/19-folder-layout.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/19-folder-layout.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/19-folder-layout.md." diff --git a/public/spec-generated/docs-payload/grading/20-entry-point-prompt.md b/public/spec-generated/docs-payload/grading/20-entry-point-prompt.md index 6009a15..c0b4d4a 100644 --- a/public/spec-generated/docs-payload/grading/20-entry-point-prompt.md +++ b/public/spec-generated/docs-payload/grading/20-entry-point-prompt.md @@ -6,9 +6,9 @@ spec_file: "20-entry-point-prompt.md" order: 20 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/20-entry-point-prompt.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/20-entry-point-prompt.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/20-entry-point-prompt.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/20-entry-point-prompt.md." diff --git a/public/spec-generated/docs-payload/grading/21-pre-conditions.md b/public/spec-generated/docs-payload/grading/21-pre-conditions.md index 2e97bd0..664ca43 100644 --- a/public/spec-generated/docs-payload/grading/21-pre-conditions.md +++ b/public/spec-generated/docs-payload/grading/21-pre-conditions.md @@ -6,9 +6,9 @@ spec_file: "21-pre-conditions.md" order: 21 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/21-pre-conditions.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/21-pre-conditions.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/21-pre-conditions.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/21-pre-conditions.md." diff --git a/public/spec-generated/docs-payload/grading/22-workbench-island.md b/public/spec-generated/docs-payload/grading/22-workbench-island.md index 1a67d24..afb8269 100644 --- a/public/spec-generated/docs-payload/grading/22-workbench-island.md +++ b/public/spec-generated/docs-payload/grading/22-workbench-island.md @@ -6,9 +6,9 @@ spec_file: "22-workbench-island.md" order: 22 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/22-workbench-island.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/22-workbench-island.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/22-workbench-island.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/22-workbench-island.md." diff --git a/public/spec-generated/docs-payload/grading/23-index-json.md b/public/spec-generated/docs-payload/grading/23-index-json.md index f3bd1df..d377a75 100644 --- a/public/spec-generated/docs-payload/grading/23-index-json.md +++ b/public/spec-generated/docs-payload/grading/23-index-json.md @@ -6,9 +6,9 @@ spec_file: "23-index-json.md" order: 23 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/23-index-json.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/23-index-json.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/23-index-json.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/23-index-json.md." diff --git a/public/spec-generated/docs-payload/grading/24-selection-aggregate.md b/public/spec-generated/docs-payload/grading/24-selection-aggregate.md index 9f72ef7..d23d0f3 100644 --- a/public/spec-generated/docs-payload/grading/24-selection-aggregate.md +++ b/public/spec-generated/docs-payload/grading/24-selection-aggregate.md @@ -6,9 +6,9 @@ spec_file: "24-selection-aggregate.md" order: 24 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/24-selection-aggregate.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/24-selection-aggregate.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/24-selection-aggregate.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/24-selection-aggregate.md." diff --git a/public/spec-generated/docs-payload/grading/25-harness-and-goal.md b/public/spec-generated/docs-payload/grading/25-harness-and-goal.md index 23c321b..72bf27f 100644 --- a/public/spec-generated/docs-payload/grading/25-harness-and-goal.md +++ b/public/spec-generated/docs-payload/grading/25-harness-and-goal.md @@ -6,9 +6,9 @@ spec_file: "25-harness-and-goal.md" order: 25 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/25-harness-and-goal.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/25-harness-and-goal.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/25-harness-and-goal.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/25-harness-and-goal.md." diff --git a/public/spec-generated/docs-payload/grading/26-monitoring-track.md b/public/spec-generated/docs-payload/grading/26-monitoring-track.md index 89ad4a1..6cff9df 100644 --- a/public/spec-generated/docs-payload/grading/26-monitoring-track.md +++ b/public/spec-generated/docs-payload/grading/26-monitoring-track.md @@ -6,9 +6,9 @@ spec_file: "26-monitoring-track.md" order: 26 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/26-monitoring-track.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/26-monitoring-track.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/26-monitoring-track.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/26-monitoring-track.md." diff --git a/scripts/sync-spec.mjs b/scripts/sync-spec.mjs index d2283d2..6ac934c 100644 --- a/scripts/sync-spec.mjs +++ b/scripts/sync-spec.mjs @@ -283,40 +283,12 @@ class SpecSync { static #injectEditWarning( { content, fileEntry } ) { - const fmMatch = content.match( /^---\n([\s\S]*?)\n---\n?/ ) - if( !fmMatch ) { - return content - } - const fmBlock = fmMatch[ 0 ] - const body = content.slice( fmBlock.length ) - - const warning = fileEntry.edit_warning - ? fileEntry.edit_warning - : SpecSync.#extractWarningFromBody( { fmBlockBody: fmMatch[ 1 ] } ) - const warningText = warning - ? warning - : `This file is auto-generated from flowmcp-spec. Do not edit directly.` - - const aside = `\n\n` - - return `${fmBlock}${aside}${body.replace( /^\n+/, '' )}` - } - - - static #extractWarningFromBody( { fmBlockBody } ) { - const match = fmBlockBody.match( /^edit_warning:\s*"?([^"\n]+)"?\s*$/m ) - return match ? match[ 1 ].trim() : '' - } - - - static #escapeHtml( str ) { - return str - .replace( /&/g, '&' ) - .replace( //g, '>' ) - .replace( /"/g, '"' ) + // Memo 142 (AUTOGEN): drop the visible "Auto-generated" aside from every + // synced page. The edit-warning provenance is retained in the frontmatter + // (`edit_warning:` / `generated_from:`) and the public mirror copy; the + // reader-facing boilerplate is removed. Returning content unchanged keeps + // the content collection byte-identical to the public mirror. + return content } diff --git a/src/components/Footer.astro b/src/components/Footer.astro index d921f38..8399f2b 100644 --- a/src/components/Footer.astro +++ b/src/components/Footer.astro @@ -38,14 +38,14 @@ const t = isDE ? { github: 'GitHub', }; -// Note: /license route does not exist — link to /schemas-and-sources/ (existing route). +// Note: license link points to the License & ToS page under /specification/. const columns = [ { title: t.project, links: [ { label: t.about, href: prefix + '/about/' }, { label: t.blog, href: prefix + '/blog/' }, - { label: t.license, href: prefix + '/schemas-and-sources/' }, + { label: t.license, href: prefix + '/specification/license-and-tos/' }, ], }, { diff --git a/src/components/Hero.astro b/src/components/Hero.astro index f2f53ce..d2bd1e6 100644 --- a/src/components/Hero.astro +++ b/src/components/Hero.astro @@ -36,10 +36,10 @@ const toolsValueDe = statsBlock.count_tools !== null && statsBlock.count_tools ! const t = isDE ? { pill: `${ featuredTitle } · Ankündigung lesen`, - headlineLine1: 'Einheitlicher Zugang zu allen Datenquellen', + headlineLine1: 'Schema-getriebener Datenzugang', headlineLine2: 'für KI-Agenten.', - mission: 'FlowMCP normalisiert hunderte Datenquellen zu einer durchsuchbaren Library aus AI-bereiten Tools — damit deine Agenten suchen, kombinieren und antworten können, ohne dass du sie zu Integrations-Maintainern machst.', - tagline: `${ dataSourcesDe } Datenquellen · ${ toolsValueDe } KI-aufrufbare Tools · KI-nativ, fuer tiefe Recherche.`, + mission: 'FlowMCP ist ein Schema-Format, das den Zugang von KI-Agenten zu beliebigen Datenquellen vereinheitlicht: den Anschluss einmal schreiben, überall wiederverwenden. Jedes Schema wird auf ein einheitliches Interface normalisiert — und bleibt getrennt von Grading und Security-Test — sodass hunderte Quellen für das Modell gleich aussehen und günstig zu pflegen bleiben.', + tagline: `${ dataSourcesDe } Datenquellen · ${ toolsValueDe } KI-aufrufbare Tools · KI-nativ, für tiefe Recherche.`, ctaPrimary: 'Dokumentation lesen →', ctaSecondary: 'FlowMCP GPT fragen', trust: 'Open Source · MIT · GitHub-nativ · Kein Vendor-Lock-in', @@ -48,9 +48,9 @@ const t = isDE ? { blogHref: featuredHref, } : { pill: `${ featuredTitle } · Read the announcement`, - headlineLine1: 'Unified access to any data source', + headlineLine1: 'Schema-driven data access', headlineLine2: 'for AI agents.', - mission: 'FlowMCP normalises hundreds of data sources into a searchable library of AI-ready tools — so your agents can search, combine, and answer without turning you into an integrations maintainer.', + mission: 'FlowMCP is a schema format that standardises how AI agents reach any data source: write the connection once, reuse it everywhere. Each schema is normalised to one uniform interface — and kept separate from its grading and security tests — so hundreds of sources look alike to the model and stay cheap to maintain.', tagline: `${ dataSourcesEn } data sources · ${ toolsValueEn } AI-callable tools · AI-native, built for deep research.`, ctaPrimary: 'Read the Docs →', ctaSecondary: 'Ask FlowMCP GPT', diff --git a/src/components/SearchCustom.astro b/src/components/SearchCustom.astro index aa4fc5f..ebee8c7 100644 --- a/src/components/SearchCustom.astro +++ b/src/components/SearchCustom.astro @@ -77,8 +77,8 @@ import Default from '@astrojs/starlight/components/Search.astro' { href: '/quickstart/what-is-flowmcp/', label: 'What is FlowMCP' }, { href: '/quickstart/quickstart/', label: 'Quickstart' }, { href: '/concepts/primitives/', label: 'Primitives' }, - { href: '/schemas-and-sources/', label: 'Schemas & Sources' }, - { href: '/reference/cli/', label: 'CLI Reference' } + { href: '/concepts/schemas/', label: 'Schemas' }, + { href: '/specification/overview/', label: 'Specification' } ] }, de: { @@ -87,8 +87,8 @@ import Default from '@astrojs/starlight/components/Search.astro' { href: '/de/quickstart/what-is-flowmcp/', label: 'Was ist FlowMCP' }, { href: '/de/quickstart/quickstart/', label: 'Schnellstart' }, { href: '/de/concepts/primitives/', label: 'Primitive' }, - { href: '/de/schemas-and-sources/', label: 'Schemas & Quellen' }, - { href: '/de/reference/cli/', label: 'CLI-Referenz' } + { href: '/de/concepts/schemas/', label: 'Schemas' }, + { href: '/de/specification/overview/', label: 'Spezifikation' } ] } } diff --git a/src/content/docs/about/faq.md b/src/content/docs/about/faq.md deleted file mode 100644 index 2b9d6df..0000000 --- a/src/content/docs/about/faq.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: FAQ -description: Frequently asked questions about FlowMCP — installation, MCP clients, schemas, contributions. ---- - -
-What is FlowMCP exactly? - -FlowMCP is a schema library + engine that normalises data sources into AI-callable tools. The library currently contains 373 production-ready schemas (v4) covering 291 data sources. The engine routes calls, validates inputs/outputs, and handles authentication. AI agents call FlowMCP; FlowMCP calls the underlying APIs. - -
- -
-Do I need an MCP-compatible client? - -No. FlowMCP is **CLI-first**. The MCP server mode is optional. If you have a client that supports dynamic tool loading, MCP works — otherwise the CLI is the preferred entry point. - -
- -
-What does CLI-first mean in practice? - -You run `flowmcp call . '{...}'` from your terminal, an LLM call, or a Node/Python script. Tools are loaded on demand — no need to keep 1608 tools in context. - -
- -
-Where do API keys live? - -API keys live in `~/.flowmcp/.env`, optionally with project overrides. The AI never sees a key — it only sees calls and responses. This is intentional: if an AI made direct REST calls, it would expose keys. - -
- -
-How do I add a new schema? - -See the [Specification](/specification/) and `repos/flowmcp-schemas-private` for the schema-creation guide. Validation rules have explicit IDs (e.g. RES001). PRs go to the schemas repo with tests. - -
- -
-Can I run FlowMCP offline? - -Yes — for schemas that hit local resources (e.g. the `geo-gtfs-toolkit` add-on with a converted SQLite DB). For schemas calling remote APIs, you still need network access. - -
- -
-What is the spec version status? - -FlowMCP currently supports the **v4** specification (active) and **v4.1** add-on extensions (e.g. `geo-gtfs-toolkit`). Older versions (v3, v2, v1.x) remain loadable for backward compatibility but receive no new schemas. - -
- -
-Why is FlowMCP "MCP" if it is CLI-first? - -The name dates from the project's start as an MCP server experiment. The substance shifted toward a CLI-first schema layer; the name persists for continuity with the MCP ecosystem. - -
- -
-Where can I report issues? - -GitHub Issues per repo. Find the most relevant repository under [github.com/FlowMCP](https://github.com/FlowMCP) and open an issue there. For schema-related questions, use `flowmcp-schemas`. For CLI bugs, use `flowmcp-cli`. - -
- -
-What is the v4 Self-Contained Skill Pattern? - -Skills bring their own parameter reference along — schema data goes **before** workflow instructions. In a lab test, skills with full parameter/enum/example info hit 5/5 success against LLMs; skills with name + description only hit 0/5. The pattern is documented in the v4 specification. - -
- -
-Are FlowMCP schemas free to use? - -Yes, MIT licensed. Some underlying APIs require keys (you supply); the data they return follows their own license — e.g. GTFS feeds under CC-BY 4.0 require attribution in your output. FlowMCP exposes that attribution in the response. - -
diff --git a/src/content/docs/about/index.mdx b/src/content/docs/about/index.mdx index 53d2a3c..e509f57 100644 --- a/src/content/docs/about/index.mdx +++ b/src/content/docs/about/index.mdx @@ -6,9 +6,9 @@ description: What FlowMCP is, why it exists, and where it stands today. About {/* PAGEFIND-META-END */} -> *FlowMCP normalises hundreds of data sources into a searchable library of AI-ready tools — so your agents can search, combine, and answer without turning you into an integrations maintainer.* +> *FlowMCP is a schema format for standardising data-source access — write the connection to an API once, and every AI agent reuses it through one uniform interface.* -FlowMCP started as a way to attach multiple data sources to a single MCP server. Today it is a schema library — **373 production-ready definitions, 291 data sources, 1608 callable tools** — all routed through one auditable engine. AI agents call FlowMCP, never the underlying APIs directly. Your API keys stay in your control. +FlowMCP started as a way to attach multiple data sources to a single MCP server. Today it is a **format**: a way to describe, normalise, and unify the tools an AI agent uses to reach a data source. A schema is written once and reused everywhere, so the model never has to re-figure-out how an API connects. The request can be reshaped before and after the call, so tools from very different sources end up looking alike to the model — and the schema is kept separate from its grading and its security test, so you can load a schema and run the security check on its own. AI agents call FlowMCP, never the underlying APIs directly, and your API keys stay in your control. ## What FlowMCP is — and isn't @@ -17,7 +17,7 @@ FlowMCP started as a way to attach multiple data sources to a single MCP server. | Aspect | Description | |--------|-------------| | **Primitive idea** | A flow of data — from heterogeneous sources, through normalised schemas, into AI pipelines | -| **Schema library** | 373 schemas (v4 production), 291 data sources, 1608 tool routes | +| **Schema format** | One declaration shape for any data source; the same format drives the CLI, MCP server mode, and the add-on toolkits | | **Primary use** | CLI tool — no MCP client holds 1608 tools in context, the CLI loads them dynamically | | **Secondary use** | MCP server mode still supported, but not the default | | **Key isolation** | Keys live in FlowMCP, never in the AI context — the AI sees calls and answers, never credentials | @@ -30,7 +30,8 @@ FlowMCP started as a way to attach multiple data sources to a single MCP server. | Misconception | Reality | |---------------|---------| -| "An MCP server" | No — CLI-first. MCP server mode is optional. | +| "An MCP server" | No — a format. MCP server mode is one optional consumer of it; the CLI is the default. | +| "A Swagger / OpenAPI spec" | More than that. Swagger describes a single API; FlowMCP unifies access *across* sources — reshaping the request before and after the call, and keeping schema, grading, and security separate. | | "A crypto library" | Started there, broadened with open data since October 2025. | | "An API wrapper collection" | No — the engine is central, schemas are thin declarations. One engine audit covers thousands of endpoints. | | "An API key manager" | Not primary. Key management is a side effect of separating AI from key. | @@ -58,8 +59,8 @@ FlowMCP makes this preparation **once, for all**: Two scenarios that show FlowMCP + AI in action — not how to build an agent, but how FlowMCP turns scattered data into one answer. -- **Deep Research** — A research tool or planning software connects an agent. The agent queries FlowMCP for relevant data sources across open data portals, government APIs, and crypto catalogs in seconds. [Read full case →](/introduction/use-cases/#use-case-1-deep-research) -- **Mobility — Catching the Connection** — A live trip planner combines static GTFS (via the `geo-gtfs-toolkit` v4.1 add-on) with real-time delay data. One CLI call, one answer. [Read full case →](/introduction/use-cases/#use-case-2-mobility--catching-the-connection) +- **Deep Research** — A research tool or planning software connects an agent. The agent queries FlowMCP for relevant data sources across open data portals, government APIs, and crypto catalogs in seconds. +- **Mobility — Catching the Connection** — A live trip planner combines static GTFS (via the `geo-gtfs-toolkit` v4.1 add-on) with real-time delay data. One CLI call, one answer. ## Production posture diff --git a/src/content/docs/best-practice/correctness-license.md b/src/content/docs/best-practice/correctness-license.md index e5f7989..ece58f3 100644 --- a/src/content/docs/best-practice/correctness-license.md +++ b/src/content/docs/best-practice/correctness-license.md @@ -6,16 +6,13 @@ spec_file: "14-correctness-license.md" order: 14 section: "Best Practice" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/best-practice/0.1.0/schema-creation/14-correctness-license.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/best-practice/0.1.0/schema-creation/14-correctness-license.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "best-practice/0.1.0/schema-creation/14-correctness-license.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: best-practice/0.1.0/schema-creation/14-correctness-license.md." --- - Assume nothing silently, fake nothing, and document where the data comes from and under which rights. Correctness and provenance are what separate a schema that *passes* from one that can be *trusted*. diff --git a/src/content/docs/best-practice/geo-conventions.md b/src/content/docs/best-practice/geo-conventions.md index d1977ea..15b9db2 100644 --- a/src/content/docs/best-practice/geo-conventions.md +++ b/src/content/docs/best-practice/geo-conventions.md @@ -6,16 +6,13 @@ spec_file: "13-geo-conventions.md" order: 13 section: "Best Practice" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/best-practice/0.1.0/schema-creation/13-geo-conventions.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/best-practice/0.1.0/schema-creation/13-geo-conventions.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "best-practice/0.1.0/schema-creation/13-geo-conventions.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: best-practice/0.1.0/schema-creation/13-geo-conventions.md." --- - Geo has a few conventions that everyone trips over once. Adopt the established defaults instead of inventing your own — it keeps schemas interoperable and spares the model a class of silent mistakes. diff --git a/src/content/docs/best-practice/load-and-scale.md b/src/content/docs/best-practice/load-and-scale.md index 697c12c..10f11af 100644 --- a/src/content/docs/best-practice/load-and-scale.md +++ b/src/content/docs/best-practice/load-and-scale.md @@ -6,16 +6,13 @@ spec_file: "12-load-and-scale.md" order: 12 section: "Best Practice" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/best-practice/0.1.0/schema-creation/12-load-and-scale.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/best-practice/0.1.0/schema-creation/12-load-and-scale.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "best-practice/0.1.0/schema-creation/12-load-and-scale.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: best-practice/0.1.0/schema-creation/12-load-and-scale.md." --- - Choose the load and storage strategy by **data size** and by the **query ability** of the source. A small static file and a large queryable corpus do not deserve the same machinery — match the mechanism to the data. diff --git a/src/content/docs/best-practice/overview.md b/src/content/docs/best-practice/overview.md index b4426a8..da7e32d 100644 --- a/src/content/docs/best-practice/overview.md +++ b/src/content/docs/best-practice/overview.md @@ -6,16 +6,13 @@ spec_file: "01-overview.md" order: 1 section: "Best Practice" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/best-practice/0.1.0/01-overview.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/best-practice/0.1.0/01-overview.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "best-practice/0.1.0/01-overview.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: best-practice/0.1.0/01-overview.md." --- - The Best-Practice track is the third FlowMCP spec track, sitting alongside the normative **Specification** and the **Grading** spec. Where those two define what a schema *is* and how it is *evaluated*, this track is **advisory and non-normative**: it gathers the recommendations and hard-won learnings for writing good schemas, not compliance rules. Nothing on these pages can disqualify a schema — they raise quality systematically, beyond the mere absence of errors. diff --git a/src/content/docs/best-practice/readable-interface.md b/src/content/docs/best-practice/readable-interface.md index 36bf9ec..37b5347 100644 --- a/src/content/docs/best-practice/readable-interface.md +++ b/src/content/docs/best-practice/readable-interface.md @@ -6,16 +6,13 @@ spec_file: "10-readable-interface.md" order: 10 section: "Best Practice" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/best-practice/0.1.0/schema-creation/10-readable-interface.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/best-practice/0.1.0/schema-creation/10-readable-interface.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "best-practice/0.1.0/schema-creation/10-readable-interface.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: best-practice/0.1.0/schema-creation/10-readable-interface.md." --- - Design the schema for the **model that calls it**, not for the API behind it. An upstream API often speaks in terse codes; the language model should not have to decode them. Translate at the edge so the surface the model sees is self-explaining. diff --git a/src/content/docs/best-practice/reference-data.md b/src/content/docs/best-practice/reference-data.md index 9d57547..2cd3aac 100644 --- a/src/content/docs/best-practice/reference-data.md +++ b/src/content/docs/best-practice/reference-data.md @@ -6,16 +6,13 @@ spec_file: "11-reference-data.md" order: 11 section: "Best Practice" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/best-practice/0.1.0/schema-creation/11-reference-data.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/best-practice/0.1.0/schema-creation/11-reference-data.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "best-practice/0.1.0/schema-creation/11-reference-data.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: best-practice/0.1.0/schema-creation/11-reference-data.md." --- - Maintain recurring lists and value formats **once**, and inherit them everywhere. Duplicated reference data drifts: one copy gets a new entry, the others quietly fall behind. A single canonical source cannot drift against itself. diff --git a/src/content/docs/concepts/clients.md b/src/content/docs/concepts/clients.md index 023e642..35d8175 100644 --- a/src/content/docs/concepts/clients.md +++ b/src/content/docs/concepts/clients.md @@ -6,6 +6,8 @@ description: Where to use schemas and agents, which clients support what, and wh Concepts +FlowMCP schemas work with any MCP-compatible client. This page covers the protocol they rely on, which clients support what, and what running them through the CLI gives you. + ## MCP — The Connecting Protocol The **Model Context Protocol (MCP)** is the standard through which AI clients access tools. It defines how tools are described, called, and how results are returned. Over 100 clients support MCP already — from Claude to ChatGPT to Cursor. @@ -38,7 +40,7 @@ These 16 clients support Elicitation — the agent can ask follow-up questions f More: [Integration Guide](/guides/integration/) -For the command-line interface — searching, activating, and calling tools from your shell — see the [FlowMCP CLI Usage](/reference/cli/) reference. +For the command-line interface — searching, activating, and calling tools from your shell — see the [Quickstart](/quickstart/quickstart/) guide. ## Which Client for Whom? diff --git a/src/content/docs/concepts/primitives.md b/src/content/docs/concepts/primitives.md index c625776..f662c55 100644 --- a/src/content/docs/concepts/primitives.md +++ b/src/content/docs/concepts/primitives.md @@ -42,7 +42,7 @@ flowmcp search flowmcp call '{"param":"value"}' ``` -The CLI handles validation, environment lookup, and HTTP execution end to end. For programmatic use, the same flow is available via the core API — see [Programmatic API](/reference/core-methods/). +The CLI handles validation, environment lookup, and HTTP execution end to end. For programmatic use, the same flow is available via the core API. ## Resources @@ -89,4 +89,4 @@ Spec: [Agents](/specification/agents/). The primitives above all run on top of a deliberate separation: the FlowMCP engine, the schemas, and the data operators are three distinct layers, and each is responsible for a different thing. The engine moves and signs every request, schemas only declare how to reach a source, and the operator owns the data and its terms. Keeping these apart is what makes the model trustworthy — a community-contributed schema can never reach beyond its declaration, the engine audit covers every call the same way, and no provider's terms get silently reinterpreted along the path. -The canonical explanation of this three-layer model, including what FlowMCP deliberately does *not* do, lives on [Schemas & Sources](/schemas-and-sources/). +The canonical explanation of this three-layer model, including what FlowMCP deliberately does *not* do, lives on [Schemas](/concepts/schemas/). diff --git a/src/content/docs/de/about/faq.md b/src/content/docs/de/about/faq.md deleted file mode 100644 index 182f982..0000000 --- a/src/content/docs/de/about/faq.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Haeufige Fragen -description: Antworten zu Installation, MCP-Clients, Schemas und Beitraegen. ---- - -
-Was ist FlowMCP genau? - -FlowMCP ist eine Schema-Library + Engine, die Datenquellen zu AI-aufrufbaren Tools normalisiert. Die Library enthaelt aktuell 373 produktionsreife Schemas (v4) ueber 291 Datenquellen. Die Engine routet Calls, validiert Inputs/Outputs und handhabt Authentifizierung. AI-Agenten rufen FlowMCP; FlowMCP ruft die zugrundeliegenden APIs. - -
- -
-Brauche ich einen MCP-kompatiblen Client? - -Nein. FlowMCP ist **CLI-First**. Der MCP-Server-Modus ist optional. Wenn dein Client dynamisches Tool-Loading unterstuetzt, funktioniert MCP — sonst ist die CLI der bevorzugte Einstieg. - -
- -
-Was bedeutet CLI-First konkret? - -Du rufst `flowmcp call . '{...}'` aus deinem Terminal, einem LLM-Call oder einem Node/Python-Script. Tools werden bei Bedarf geladen — keine Notwendigkeit, 1608 Tools im Kontext zu halten. - -
- -
-Wo leben API-Keys? - -API-Keys leben in `~/.flowmcp/.env`, optional mit Projekt-Overrides. Die AI sieht nie einen Key — nur Calls und Antworten. Das ist Absicht: bei direkten REST-Calls aus der AI heraus wuerden Keys exposed. - -
- -
-Wie fuege ich ein neues Schema hinzu? - -Siehe [Specification](/specification/) und `repos/flowmcp-schemas-private` fuer den Schema-Creation-Guide. Validation-Rules haben explizite IDs (z.B. RES001). PRs gehen ins Schemas-Repo mit Tests. - -
- -
-Kann ich FlowMCP offline nutzen? - -Ja — fuer Schemas mit lokalen Ressourcen (z.B. das `geo-gtfs-toolkit`-Add-on mit konvertierter SQLite-DB). Fuer Schemas, die Remote-APIs callen, brauchst du weiter Netz. - -
- -
-Was ist der Spec-Versions-Status? - -FlowMCP unterstuetzt aktuell die **v4**-Spezifikation (aktiv) und **v4.1**-Add-on-Erweiterungen (z.B. `geo-gtfs-toolkit`). Aeltere Versionen (v3, v2, v1.x) bleiben aus Kompatibilitaetsgruenden ladbar, erhalten aber keine neuen Schemas. - -
- -
-Warum heisst FlowMCP "MCP", wenn es CLI-First ist? - -Der Name kommt vom Projektstart als MCP-Server-Experiment. Die Substanz hat sich Richtung CLI-First-Schema-Layer verschoben; der Name bleibt fuer Kontinuitaet mit dem MCP-Oekosystem. - -
- -
-Wo melde ich Issues? - -GitHub Issues pro Repo. Finde das passende Repository unter [github.com/FlowMCP](https://github.com/FlowMCP) und oeffne dort ein Issue. Fuer Schema-Fragen: `flowmcp-schemas`. Fuer CLI-Bugs: `flowmcp-cli`. - -
- -
-Was ist das v4 Self-Contained Skill Pattern? - -Skills bringen ihre eigene Parameter-Referenz mit — Schema-Daten stehen **vor** Workflow-Instruktionen. In einem Labortest erreichten Skills mit vollen Parameter/Enum/Beispiel-Infos 5/5 Erfolg gegen LLMs; Skills mit nur Name + Beschreibung 0/5. Das Pattern ist in der v4-Spec dokumentiert. - -
- -
-Sind FlowMCP-Schemas frei nutzbar? - -Ja, MIT-lizensiert. Manche APIs brauchen Keys (du lieferst sie); die zurueckgegebenen Daten folgen deren Lizenz — z.B. GTFS-Feeds unter CC-BY 4.0 brauchen Attribution im Output. FlowMCP zeigt diese Attribution in der Response. - -
diff --git a/src/content/docs/de/about/index.mdx b/src/content/docs/de/about/index.mdx index 7d090e0..2267bba 100644 --- a/src/content/docs/de/about/index.mdx +++ b/src/content/docs/de/about/index.mdx @@ -6,9 +6,9 @@ description: Was FlowMCP ist, warum es existiert, und wo es heute steht. Ueber FlowMCP {/* PAGEFIND-META-END */} -> *FlowMCP normalisiert hunderte Datenquellen zu einer durchsuchbaren Library aus AI-bereiten Tools — damit deine Agenten suchen, kombinieren und antworten können, ohne dass du sie zu Integrations-Maintainern machst.* +> *FlowMCP ist ein Schema-Format zur Standardisierung des Datenquellen-Zugangs — den Anschluss an eine API einmal schreiben, und jeder KI-Agent nutzt ihn über ein einheitliches Interface wieder.* -FlowMCP begann als Versuch, mehrere Datenquellen an einen einzigen MCP-Server anzubinden. Heute ist es eine Schema-Library — **373 produktionsreife Definitionen, 291 Datenquellen, 1608 aufrufbare Tools** — alle ueber eine zentrale, auditierbare Engine geleitet. AI-Agenten rufen FlowMCP — nie die zugrundeliegenden APIs direkt. Deine API-Keys bleiben in deiner Kontrolle. +FlowMCP begann als Versuch, mehrere Datenquellen an einen einzigen MCP-Server anzubinden. Heute ist es ein **Format**: eine Art, die Tools zu beschreiben, zu normalisieren und zu vereinheitlichen, mit denen ein KI-Agent eine Datenquelle erreicht. Ein Schema wird einmal geschrieben und überall wiederverwendet, sodass das Modell nie neu herausfinden muss, wie eine API sich anschließt. Der Request kann vor und nach dem Aufruf umgeformt werden, sodass Tools sehr unterschiedlicher Quellen für das Modell gleich aussehen — und das Schema bleibt getrennt von seinem Grading und seinem Security-Test, sodass du ein Schema laden und den Security-Check separat fahren kannst. KI-Agenten rufen FlowMCP, nie die zugrundeliegenden APIs direkt, und deine API-Keys bleiben in deiner Kontrolle. ## Was FlowMCP ist — und nicht ist @@ -17,7 +17,7 @@ FlowMCP begann als Versuch, mehrere Datenquellen an einen einzigen MCP-Server an | Aspekt | Beschreibung | |--------|--------------| | **Primitive Idee** | Ein Fluss von Daten — aus heterogenen Quellen, durch normalisierte Schemas, in AI-Pipelines | -| **Schema-Library** | 373 Schemas (v4-Produktion), 291 Datenquellen, 1608 Tool-Routes | +| **Schema-Format** | Eine Deklarations-Form für jede Datenquelle; dasselbe Format treibt die CLI, den MCP-Server-Modus und die Add-on-Toolkits | | **Primaerer Use** | CLI-Tool — kein MCP-Client haelt 1608 Tools im Kontext, die CLI laedt sie dynamisch | | **Sekundaerer Use** | MCP-Server-Modus weiter unterstuetzt, aber nicht der Default | | **Key-Isolation** | Keys leben in FlowMCP, nie im AI-Kontext — die AI sieht Calls und Antworten, nie Credentials | @@ -30,7 +30,8 @@ FlowMCP begann als Versuch, mehrere Datenquellen an einen einzigen MCP-Server an | Missverstaendnis | Realitaet | |------------------|-----------| -| "Ein MCP-Server" | Nein — CLI-First. MCP-Server-Modus ist optional. | +| "Ein MCP-Server" | Nein — ein Format. Der MCP-Server-Modus ist ein optionaler Konsument davon; die CLI ist der Default. | +| "Eine Swagger-/OpenAPI-Spec" | Mehr als das. Swagger beschreibt eine einzelne API; FlowMCP vereinheitlicht den Zugang *über* Quellen hinweg — formt den Request vor und nach dem Aufruf um und haelt Schema, Grading und Security getrennt. | | "Eine Krypto-Library" | Begann dort, ist seit Oktober 2025 mit Open Data deutlich breiter. | | "Eine API-Wrapper-Sammlung" | Nein — Engine ist zentral, Schemas sind duenne Deklarationen. Ein Audit der Engine deckt Tausende Endpunkte ab. | | "Ein API-Key-Manager" | Nicht primaer. Key-Management ist Nebenprodukt der Trennung AI ↔ Key. | @@ -58,8 +59,8 @@ FlowMCP macht diese Vorbereitung **einmal, fuer alle**: Zwei Szenarien, die FlowMCP + AI im Einsatz zeigen — nicht wie man einen Agent baut, sondern wie FlowMCP aus verstreuten Daten eine Antwort macht. -- **Deep Research** — Eine Recherche- oder Planungssoftware bindet einen Agent an. Der Agent fragt FlowMCP nach passenden Datenquellen ueber Open-Data-Portale, Behoerden-APIs und Krypto-Kataloge — in Sekunden. [Voller Case →](/de/introduction/use-cases/#use-case-1-deep-research) -- **Mobility — Anschluss erreichen** — Ein Live-Reiseplaner kombiniert statische GTFS-Daten (ueber das `geo-gtfs-toolkit` v4.1 Add-on) mit Echtzeit-Verspaetungen. Ein CLI-Call, eine Antwort. [Voller Case →](/de/introduction/use-cases/#use-case-2-mobility--anschluss-erreichen) +- **Deep Research** — Eine Recherche- oder Planungssoftware bindet einen Agent an. Der Agent fragt FlowMCP nach passenden Datenquellen ueber Open-Data-Portale, Behoerden-APIs und Krypto-Kataloge — in Sekunden. +- **Mobility — Anschluss erreichen** — Ein Live-Reiseplaner kombiniert statische GTFS-Daten (ueber das `geo-gtfs-toolkit` v4.1 Add-on) mit Echtzeit-Verspaetungen. Ein CLI-Call, eine Antwort. ## Production-Posture diff --git a/src/content/docs/de/concepts/clients.md b/src/content/docs/de/concepts/clients.md index ef1c3d3..597e720 100644 --- a/src/content/docs/de/concepts/clients.md +++ b/src/content/docs/de/concepts/clients.md @@ -6,6 +6,8 @@ description: Wo man Schemas und Agents nutzen kann, welche Clients was unterstue Concepts +FlowMCP-Schemas funktionieren mit jedem MCP-kompatiblen Client. Diese Seite behandelt das zugrunde liegende Protokoll, welche Clients was unterstuetzen und was der Betrieb ueber die CLI bringt. + ## MCP — Das verbindende Protokoll Das **Model Context Protocol (MCP)** ist der Standard, ueber den KI-Clients auf Tools zugreifen. Es definiert, wie Tools beschrieben, aufgerufen und wie Ergebnisse zurueckgeliefert werden. Ueber 100 Clients unterstuetzen MCP bereits — von Claude ueber ChatGPT bis Cursor. @@ -38,7 +40,7 @@ Diese 16 Clients unterstuetzen Elicitation — der Agent kann Rueckfragen stelle Mehr dazu: [Integration Guide](/de/guides/integration/) -Fuer die Commandline-Schnittstelle — Tools im Terminal suchen, aktivieren und aufrufen — siehe die [FlowMCP CLI-Nutzung](/de/reference/cli/) Referenz. +Fuer die Commandline-Schnittstelle — Tools im Terminal suchen, aktivieren und aufrufen — siehe den [Schnellstart](/de/quickstart/quickstart/). ## Welcher Client fuer wen? diff --git a/src/content/docs/de/concepts/primitives.md b/src/content/docs/de/concepts/primitives.md index 3e89e11..0c47dda 100644 --- a/src/content/docs/de/concepts/primitives.md +++ b/src/content/docs/de/concepts/primitives.md @@ -42,7 +42,7 @@ flowmcp search flowmcp call '{"param":"wert"}' ``` -Die CLI uebernimmt Validierung, Environment-Lookup und HTTP-Execution End-to-End. Fuer programmatische Nutzung steht derselbe Flow ueber die Core-API zur Verfuegung — siehe [Programmatic API](/de/reference/core-methods/). +Die CLI uebernimmt Validierung, Environment-Lookup und HTTP-Execution End-to-End. Fuer programmatische Nutzung steht derselbe Flow ueber die Core-API zur Verfuegung. ## Resources @@ -89,4 +89,4 @@ Spec: [Agents](/specification/agents/). Die obigen Primitive laufen alle auf einer bewussten Trennung: Die FlowMCP-Engine, die Schemas und die Daten-Betreiber sind drei eigenstaendige Ebenen, und jede ist fuer etwas anderes zustaendig. Die Engine bewegt und signiert jeden Request, Schemas deklarieren nur, wie eine Quelle erreicht wird, und der Betreiber besitzt die Daten und deren Bedingungen. Diese Trennung macht das Modell vertrauenswuerdig — ein Community-Schema kann nie ueber seine Deklaration hinausgreifen, das Engine-Audit deckt jeden Call gleich ab, und die Bedingungen eines Anbieters werden auf dem Weg nicht still umgedeutet. -Die kanonische Erklaerung dieses Drei-Ebenen-Modells, inkl. dem, was FlowMCP bewusst *nicht* tut, steht auf [Schemas & Quellen](/de/schemas-and-sources/). +Die kanonische Erklaerung dieses Drei-Ebenen-Modells, inkl. dem, was FlowMCP bewusst *nicht* tut, steht auf [Schemas](/de/concepts/schemas/). diff --git a/src/content/docs/de/ecosystem/agentprobe.md b/src/content/docs/de/ecosystem/agentprobe.md deleted file mode 100644 index afe3e5b..0000000 --- a/src/content/docs/de/ecosystem/agentprobe.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: AgentProbe -description: Multi-Protokoll-Validierung fuer MCP-Server, A2A-Agenten und x402-Endpunkte ---- - -Ecosystem - - -:::caution[Experimentell — Vorab-Lesung] -**Hinweis zu x402:** AgentProbe validiert Endpunkte, die x402 nutzen koennen. Das x402-Protokoll selbst ist experimentell — bitte die vier Punkte unten lesen, bevor du dich auf Ergebnisse verlaesst. - -**Was x402 ist:** Ein maschinenlesbares Zahlungsprotokoll auf Basis des HTTP-Status-Codes 402 (Payment Required). Es erlaubt API-Endpunkten — auch MCP-Tools — Zahlungsanforderungen standardisiert zu signalisieren und Zahlungsbelege entgegenzunehmen. - -**Warum experimentell:** Die x402-Spezifikation, der Netzwerk-Support (Base, Solana, Stacks) und die Referenz-Implementierungen befinden sich 2026 noch in Entwicklung. Es gibt kein Service-Level-Agreement, keine produktionsreife Zuverlaessigkeitsgarantie, und das Wire-Format kann sich zwischen Minor-Versionen aendern. - -**Wann einzusetzen:** Hackathon-Demos, payment-gated MCP-Tool-Prototypen, Proof-of-Concepts, Forschungs-Szenarien. Geeignet fuer geschlossene Tests mit bekannten Clients. - -**Was es NICHT ist:** Kein produktives Zahlungs-Gateway. Kein Ersatz fuer etablierte Payment-Service-Provider (Stripe, PayPal). Kein Compliance-zertifiziertes Zahlungssystem. Schicken Sie keine echten Kundenumsaetze ueber diesen Stack ohne zusaetzliche Sicherungen. -::: - -[AgentProbe](https://github.com/FlowMCP/mcp-agent-validator) ist ein webbasierter Multi-Protokoll-Validator fuer AI-Agent-Endpunkte. Gib eine URL ein und erhalte eine sofortige Bewertung ueber acht Protokoll-Ebenen. - -**Live-Demo:** [agentprobe.xyz](https://agentprobe.xyz) - -## Was es macht - -- **Eingabe:** Eine einzelne Agent-Endpunkt-URL -- **Bewertung:** Fuehrt die `mcp-agent-assessment`-Pipeline mit protokollspezifischen Validatoren aus -- **Ausgabe:** Einheitliche Bewertungen pro Protokoll-Ebene plus Roh-Assessment-Daten - -Eine URL genuegt. AgentProbe erkennt, welche Protokolle der Endpunkt unterstuetzt und validiert jedes einzeln. - -## Protokoll-Ebenen - -AgentProbe bewertet acht Protokoll-Ebenen: - -| Ebene | Was geprueft wird | -|-------|------------------| -| **HTTP** | Konnektivitaet, HTTPS, SSL-Validierung, CORS, HTTP/2-Erkennung | -| **MCP** | Server-Discovery, Tool/Resource/Prompt-Auflistung, Capability-Erkennung | -| **A2A / AP2** | Agent-Card-Validierung, AP2-Version und Rollenerkennung via `capabilities.extensions` und `X-A2A-Extensions`-Header | -| **x402** | Erkennung zahlungspflichtiger Endpunkte mit Scheme-, Netzwerk- und Token-Analyse | -| **OAuth** | Discovery der Authorization-Server-Metadaten | -| **MCP Apps** | UI-Resource-Erkennung fuer MCP-Anwendungen | -| **HTML** | Website-Erkennung, Content-Type, SSL-Status, HTTP/2 | -| **ERC-8004** | On-Chain-Agent-Registry-Lookup mit OASF-Klassifikation, Reputation und Metadaten-Extraktion | - -:::note -Nicht jeder Endpunkt unterstuetzt alle Protokolle. AgentProbe behandelt nicht unterstuetzte Ebenen elegant und zeigt nur Ergebnisse fuer erkannte Protokolle an. -::: - -## Architektur - -```mermaid -flowchart TD - U[URL Input] --> S[Server] --> A[mcp-agent-assessment] - A --> H[HTTP] - A --> M[MCP] - A --> AP[A2A / AP2] - A --> X[x402] - A --> O[OAuth] - H --> R[Results UI] - M --> R - AP --> R - X --> R - O --> R -``` - -Der Server empfaengt eine URL, leitet sie an die einheitliche Assessment-Pipeline weiter und gibt strukturierte Ergebnisse fuer jede Protokoll-Ebene zurueck. - -## API-Endpunkte - -### `POST /api/validate` - -Gibt ein strukturiertes Validierungsergebnis mit separaten Abschnitten fuer jedes Protokoll zurueck. - -```bash -curl -X POST https://agentprobe.xyz/api/validate \ - -H 'Content-Type: application/json' \ - -d '{"url": "https://your-endpoint.example.com/mcp"}' -``` - -Die Antwort enthaelt `mcp`-, `a2a`-, `ui`- (MCP Apps) und `oauth`-Objekte, jeweils mit `status`, `categories`, `summary` und `messages`. - -### `POST /api/assess` - -Gibt das Roh-Assessment-Ergebnis von `mcp-agent-assessment` mit vollstaendigen Ebenen-Details zurueck. - -```bash -curl -X POST https://agentprobe.xyz/api/assess \ - -H 'Content-Type: application/json' \ - -d '{"url": "https://your-endpoint.example.com/mcp"}' -``` - -Optionale Parameter: - -| Key | Typ | Beschreibung | -|-----|-----|-------------| -| `timeout` | number | Timeout in Millisekunden | -| `erc8004` | object | ERC-8004-Konfiguration mit `rpcNodes` | - -### `POST /api/lookup` - -Abfrage der ERC-8004 On-Chain-Registry fuer Agent-Registrierungsdaten, Endpunkte, OASF-Klassifikation und Reputation. - -```bash -curl -X POST https://agentprobe.xyz/api/lookup \ - -H 'Content-Type: application/json' \ - -d '{"agentId": 2340, "chainId": 8453}' -``` - -| Key | Typ | Beschreibung | Pflicht | -|-----|-----|-------------|---------| -| `agentId` | number | Agent-Token-ID in der ERC-8004-Registry | Ja | -| `chainId` | number oder string | Chain-ID (z.B. `8453` fuer Base) oder CAIP-2 (z.B. `eip155:8453`) | Ja | -| `rpcNodes` | object | Benutzerdefinierte RPC-Nodes pro Chain-Alias | Nein | - -## Eigenen MCP-Server validieren - -1. **MCP-Server deployen** - - Stelle sicher, dass dein MCP-Server oeffentlich erreichbar ist (z.B. via ngrok oder Cloud-Deployment). - -2. **AgentProbe oeffnen** - - Gehe zu [agentprobe.xyz](https://agentprobe.xyz) in deinem Browser. - -3. **Endpunkt-URL eingeben** - - Fuege deine MCP-Server-URL ein (z.B. `https://your-server.example.com/mcp`) und klicke auf Validieren. - -4. **Ergebnisse pruefen** - - AgentProbe zeigt Bewertungen fuer jede Protokoll-Ebene. Gruen bedeutet unterstuetzt und valide, Rot bedeutet Probleme erkannt, Grau bedeutet nicht zutreffend. - -Oder nutze die API direkt: - -```bash -curl -X POST https://agentprobe.xyz/api/validate \ - -H 'Content-Type: application/json' \ - -d '{"url": "https://your-server.example.com/mcp"}' -``` - -## Authentifizierung - -Authentifizierung ist optional. Wenn `API_TOKEN` nicht gesetzt ist, ist die API offen (Dev-Modus). - -Wenn `API_TOKEN` gesetzt ist, werden zwei Authentifizierungsmethoden unterstuetzt: - -| Methode | Funktionsweise | -|---------|---------------| -| **Session Cookie** | Browser besucht die UI und erhaelt automatisch ein Session-Cookie | -| **Bearer Token** | Externe Skripte senden `Authorization: Bearer `-Header | - -```bash -# Mit Bearer Token -curl -X POST https://agentprobe.xyz/api/validate \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer your-token-here' \ - -d '{"url": "https://your-endpoint.example.com"}' -``` - -## Abhaengigkeiten - -AgentProbe baut auf dem FlowMCP-Validator-Oekosystem auf: - -| Paket | Zweck | -|-------|-------| -| [mcp-agent-assessment](https://github.com/FlowMCP/mcp-server-assessment) | Einheitliche Assessment-Pipeline | -| [a2a-agent-validator](https://github.com/FlowMCP/a2a-agent-validator) | A2A-Agent-Card- und AP2-Erkennung | -| [x402-mcp-validator](https://github.com/FlowMCP/x402-mcp-validator) | x402-Zahlungsprotokoll-Validierung | -| [mcp-apps-validator](https://github.com/FlowMCP/mcp-apps-validator) | MCP Apps UI-Resource-Erkennung | -| [erc8004-registry-parser](https://github.com/FlowMCP/erc8004-registry-parser) | ERC-8004 On-Chain-Registry-Parsing | - -## Links - -- **Live-Demo**: [agentprobe.xyz](https://agentprobe.xyz) -- **GitHub**: [FlowMCP/mcp-agent-validator](https://github.com/FlowMCP/mcp-agent-validator) -- **Video**: [Auf YouTube ansehen](https://www.youtube.com/watch?v=gnmsCEly3fA) -- **DoraHacks**: [dorahacks.io/buidl/39293](https://dorahacks.io/buidl/39293) diff --git a/src/content/docs/de/ecosystem/x402.mdx b/src/content/docs/de/ecosystem/x402.mdx deleted file mode 100644 index fa9b211..0000000 --- a/src/content/docs/de/ecosystem/x402.mdx +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: x402-Zahlungsprotokoll -description: Zahlungsgeschuetzten Zugang zu MCP-Tools hinzufuegen ---- -{/* PAGEFIND-META-START */} -Ecosystem -{/* PAGEFIND-META-END */} - -import InstallNote from '../../../../components/InstallNote.astro'; - -:::caution[Experimentell — Vorab-Lesung] -**Was x402 ist:** Ein maschinenlesbares Zahlungsprotokoll auf Basis des HTTP-Status-Codes 402 (Payment Required). Es erlaubt API-Endpunkten — auch MCP-Tools — Zahlungsanforderungen standardisiert zu signalisieren und Zahlungsbelege entgegenzunehmen. - -**Warum experimentell:** Die x402-Spezifikation, der Netzwerk-Support (Base, Solana, Stacks) und die Referenz-Implementierungen befinden sich 2026 noch in Entwicklung. Es gibt kein Service-Level-Agreement, keine produktionsreife Zuverlaessigkeitsgarantie, und das Wire-Format kann sich zwischen Minor-Versionen aendern. - -**Wann einzusetzen:** Hackathon-Demos, payment-gated MCP-Tool-Prototypen, Proof-of-Concepts, Forschungs-Szenarien. Geeignet fuer geschlossene Tests mit bekannten Clients. - -**Was es NICHT ist:** Kein produktives Zahlungs-Gateway. Kein Ersatz fuer etablierte Payment-Service-Provider (Stripe, PayPal). Kein Compliance-zertifiziertes Zahlungssystem. Schicken Sie keine echten Kundenumsaetze ueber diesen Stack ohne zusaetzliche Sicherungen. -::: - -Das [x402-Protokoll](https://www.x402.org/) erweckt den HTTP-Statuscode 402 (Payment Required) als maschinenlesbares Zahlungsprotokoll fuer APIs zum Leben. Der [x402-mcp-validator](https://github.com/FlowMCP/x402-mcp-validator) validiert MCP-Server auf x402-Konformitaet -- verbindet sich mit Servern, erkennt Tools, prueft auf Zahlungsanforderungen und validiert Zahlungsoptionen gegen die Spezifikation. - -## Wie x402 mit MCP funktioniert - -Wenn ein MCP-Tool eine Zahlung erfordert, ist der Ablauf: - -1. **Client ruft ein Tool auf** auf dem MCP-Server -2. **Server antwortet mit 402** inklusive Zahlungsanforderungen (scheme, network, amount, asset, payTo) -3. **Client verarbeitet die Zahlung** ueber das angegebene Zahlungsnetzwerk -4. **Client wiederholt den Tool-Aufruf** mit einem Zahlungsbeleg im Header -5. **Server validiert die Zahlung** und fuehrt das Tool aus - -Dies ermoeglicht API-Monetarisierung auf Tool-Ebene -- verschiedene Tools koennen unterschiedliche Preise haben, und kostenlose Tools koennen neben kostenpflichtigen auf demselben Server existieren. - -## x402 MCP Validator - -Der Validator verbindet sich End-to-End mit einem MCP-Server und gibt einen strukturierten Snapshot zurueck: - -```javascript -import { McpServerValidator } from 'x402-mcp-validator' - -const { status, messages, categories, entries } = await McpServerValidator.start( { - endpoint: 'https://your-mcp-server.example.com/mcp', - timeout: 15000 -} ) - -console.log( `Status: ${status ? 'PASS' : 'FAIL'}` ) -console.log( `Tools: ${entries['tools'].length}` ) -console.log( `x402: ${categories['supportsX402']}` ) -console.log( `Networks: ${JSON.stringify( entries['x402']['networks'] )}` ) -``` - -### `.start()` - -Verbindet sich mit einem MCP-Server, erkennt Capabilities, prueft auf x402-Zahlungsunterstuetzung, validiert Zahlungsanforderungen, misst Latenz und gibt einen strukturierten Snapshot zurueck. - -| Key | Typ | Beschreibung | Pflicht | -|-----|-----|-------------|---------| -| `endpoint` | string | MCP-Server-URL | Ja | -| `timeout` | number | Verbindungs-Timeout in ms (Standard `10000`) | Nein | - -**Gibt zurueck:** `{ status, messages, categories, entries }` - -### `.compare()` - -Vergleicht zwei Snapshots von `.start()` und gibt einen strukturierten Diff mit hinzugefuegten, entfernten und geaenderten Elementen pro Abschnitt zurueck. - -```javascript -const before = await McpServerValidator.start( { endpoint: 'https://server.example.com/mcp' } ) -// ... Zeit vergeht, Server aendert sich ... -const after = await McpServerValidator.start( { endpoint: 'https://server.example.com/mcp' } ) - -const { status, messages, hasChanges, diff } = McpServerValidator.compare( { before, after } ) - -console.log( `Changes detected: ${hasChanges}` ) -console.log( `Tools added: ${diff['tools']['added'].length}` ) -console.log( `Tools removed: ${diff['tools']['removed'].length}` ) -``` - -| Key | Typ | Beschreibung | Pflicht | -|-----|-----|-------------|---------| -| `before` | object | Snapshot eines frueheren `.start()`-Aufrufs | Ja | -| `after` | object | Snapshot eines spaeteren `.start()`-Aufrufs | Ja | - -**Gibt zurueck:** `{ status, messages, hasChanges, diff }` - -## Kategorien - -Der Validator klassifiziert jeden Server mit 12 booleschen Flags: - -| Flag | Beschreibung | -|------|-------------| -| `isReachable` | Server hat auf HEAD-Anfrage geantwortet | -| `supportsMcp` | MCP-Handshake abgeschlossen | -| `hasTools` | Server stellt mindestens ein Tool bereit | -| `hasResources` | Server stellt mindestens eine Resource bereit | -| `hasPrompts` | Server stellt mindestens einen Prompt bereit | -| `supportsX402` | Mindestens ein Tool hat einen 402-Zahlungsfehler zurueckgegeben | -| `hasValidPaymentRequirements` | Mindestens eine Zahlungsoption hat die Validierung bestanden | -| `supportsExactScheme` | Hat Zahlungsoptionen mit `scheme: 'exact'` | -| `supportsEvm` | Hat Zahlungsoptionen mit `network: 'eip155:*'` | -| `supportsSolana` | Hat Zahlungsoptionen mit `network: 'solana:*'` | -| `supportsTasks` | Server bewirbt Tasks-Capability | -| `supportsMcpApps` | Server bewirbt mcpApps-Capability | - -## Validierungs-Pipeline - -Der Validator verarbeitet einen MCP-Server in sechs aufeinanderfolgenden Schritten: - -1. **Connect** -- Verbindet sich mit dem MCP-Server via StreamableHTTP mit SSE-Fallback. -2. **Discover** -- Erkennt Tools, Resources, Prompts und Capabilities ueber das MCP-Protokoll. -3. **Classify** -- Klassifiziert Server-Capabilities in die 12 booleschen Kategorien. -4. **Probe** -- Prueft jedes Tool auf x402-Zahlungsanforderungen (HTTP 402 / JSON-RPC -32402). -5. **Validate** -- Validiert Zahlungsoptionen: Scheme, Network, Amount, Asset, payTo, Checksummen. -6. **Build Snapshot** -- Erstellt den strukturierten Snapshot mit Kategorien, Eintraegen und Validierungsmeldungen. - -## Validierungscodes - -Der Validator verwendet strukturierte Fehlercodes, organisiert nach Kategorie: - -
-VAL -- Eingabevalidierung - -Codes `VAL-001` bis `VAL-015` decken die Eingabeparameter-Validierung fuer `.start()` und `.compare()` ab. Beispiele: fehlender Endpunkt, ungueltiges URL-Format, fehlende Snapshots fuer Vergleich. -
- -
-CON -- MCP-Verbindung - -Codes `CON-001` bis `CON-011` decken Server-Konnektivitaet und MCP-Handshake-Probleme ab. Beispiele: Server nicht erreichbar, Handshake fehlgeschlagen, tools/list-Anfrage fehlgeschlagen. -
- -
-PAY -- Zahlungsvalidierung - -Codes `PAY-001` bis `PAY-102` decken die x402-Zahlungsanforderungs-Validierung im Detail ab. Pruefungen umfassen: x402-Version, Resource-Format, Accepts-Array, Scheme, Netzwerk-Praefix, Betragsformat, Asset-Adresse, payTo-Adresse mit Checksummen-Validierung und Timeout-Werte. -
- -
-PRB -- Probe - -Codes `PRB-004` und `PRB-005` decken Probe-Level-Probleme ab wie unerwartete Ausnahmen und keine verfuegbaren Tools. -
- -
-AUTH -- OAuth - -Codes `AUTH-002` bis `AUTH-011` decken OAuth-Discovery ab einschliesslich Metadaten, PKCE-Unterstuetzung, Protected-Resource-Metadaten, Client-Registrierung und Scope-Erkennung. -
- -
-CMP -- Vergleich - -Codes `CMP-001` bis `CMP-003` decken die Snapshot-Vergleichs-Integritaet ab: unterschiedliche Server-Endpunkte, fehlende Zeitstempel und chronologische Reihenfolge. -
- -:::tip -Jede Validierungsmeldung enthaelt einen Fehlercode, Schweregrad (ERROR, WARNING, INFO) und eine menschenlesbare Beschreibung. Verwende die Codes, um spezifische Probleme programmatisch zu identifizieren und zu behandeln. -::: - -## Links - -- **GitHub**: [FlowMCP/x402-mcp-validator](https://github.com/FlowMCP/x402-mcp-validator) -- **x402-Spezifikation**: [x402.org](https://www.x402.org/) - - diff --git a/src/content/docs/de/introduction/faq.md b/src/content/docs/de/introduction/faq.md index bd30428..5891aa0 100644 --- a/src/content/docs/de/introduction/faq.md +++ b/src/content/docs/de/introduction/faq.md @@ -22,8 +22,6 @@ Weil echte Fragen im Alltag nie einfach sind. Eine einzelne Datenquelle liefert eine einzelne Antwort. Erst die Kombination macht die Antwort wirklich nuetzlich. Genau das machen unsere Schemas moeglich. -Konkrete Beispiele: [Use Cases →](/de/introduction/use-cases/) - ## Brauche ich einen API-Key? Fuer die meisten unserer Schemas nicht. Wir starten bewusst mit Datenquellen, die **ohne API-Key** frei zugaenglich sind — Wetterdaten, OEPNV-Fahrplaene, Geocoding, Fahrrad-Sharing und mehr. diff --git a/src/content/docs/de/introduction/use-cases.md b/src/content/docs/de/introduction/use-cases.md deleted file mode 100644 index d541b90..0000000 --- a/src/content/docs/de/introduction/use-cases.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Use Cases -description: Zwei Szenarien, die FlowMCP + AI im Einsatz zeigen — wie verstreute Daten zu einer Antwort werden. ---- - -About - - -Zwei Szenarien, die FlowMCP + AI im Einsatz zeigen — nicht wie man einen Agent baut, sondern wie FlowMCP aus verstreuten Datenquellen eine nutzbare Antwort macht. Beide Cases setzen voraus, dass ein AI-Agent (Claude, GPT oder aehnlich) an ein Recherche-Tool, eine Planungssoftware oder einen CLI-Workflow angebunden ist und FlowMCP-CLI als Datenzugriffs-Schicht laeuft. - ---- - -## Use Case 1: Deep Research - -### Setup - -Ein Recherche-Workflow — eine eigene Pipeline, ein internes Dashboard oder ein Notion-/Obsidian-Workspace — hat einen AI-Agent angebunden. Aufgabe des Agents: Daten aus vielen Quellen zusammentragen, um eine Forschungsfrage zu scopen oder zu beantworten. FlowMCP-CLI laeuft daneben als Werkzeug des Agents, um normalisierte Datenquellen zu finden und aufzurufen. - -### Der Prompt - -> Wir planen ein Open-Data-Projekt zur Luftqualitaet in deutschen Innenstaedten. Sammle Datenquellen zu Feinstaub-Messstationen, die Open-Data-Portale von Berlin, Muenchen und Hamburg, Wetter-Stationen zur Korrelation, und gib mir eine Liste mit Provider, Lizenz, Sample-Endpoint und Aktualisierungsfrequenz. - -### Was FlowMCP macht - -1. **Katalog durchsuchen** — Der Agent ruft `flowmcp search` mit Tags wie `airquality`, `opendata`, `berlin`, `weather`. FlowMCP gibt passende Schemas ueber viele Provider hinweg zurueck — mit Provider-Name, Lizenz und Kurzbeschreibung. -2. **Pro Schema einen Sample-Call** — Bei vielversprechenden Treffern macht der Agent einen Sample-Call (`flowmcp call `). FlowMCP haelt die API-Keys, signiert den Request und liefert die normalisierte Antwort. Der Agent sieht die Datenform, nie die Credentials. -3. **Kombinieren und zusammenfassen** — Der Agent merget Ergebnisse aus Bundes-, Stadt- und Wetter-Quellen, dedupliziert ueberlappende Stationen und produziert eine Tabelle, mit der der User sofort arbeiten kann. - -### Feste Datenquellen, eine Antwort - -Der Agent greift auf einen festen Satz kuratierter Datenquellen zurueck — Bundes-, Stadt- und Wetter-Feeds, die einmal normalisiert wurden und nun bei jeder Anfrage wiederverwendet werden. Weil diese Quellen eine einheitliche Form und einen gemeinsamen Auth-Pfad teilen, fuehrt der Agent sie zu einer konsolidierten Antwort zusammen, statt fuer jede einzelne eine eigene API-Doku zu lesen. Die Arbeit, jede Quelle zu verstehen, passiert einmal — im Schema — und jeder Agent profitiert anschliessend davon. - -> Statt der AI hunderte Tokens API-Doku pro Anfrage zu fuettern, sucht sie in einem normalisierten Katalog. Eine Schema-Investition, beliebig viele Agenten. - -### Naechste Schritte - -- [CLI-Setup →](/de/quickstart/quickstart/) — erster Call in unter 5 Minuten - ---- - -## Use Case 2: Mobility — Anschluss erreichen - -### Setup - -Der GTFS-Pilot ist real und dokumentiert (siehe [GTFS-Pilot-Guide](/de/guides/gtfs-pilot/)). FlowMCP v4.1 liefert das Add-on-Konzept: externe Toolkits wie `geo-gtfs-toolkit` erweitern die CLI um lokale SQLite-Datenbanken fuer statische Fahrplaene. Die Kombination — statischer GTFS-Lookup plus Live-REST-API fuer Verspaetungen — macht diesen Case zu einem einzigen CLI-Call statt einer Jongliererei zwischen zwei Agenten. - -### Der Prompt - -> Ich bin am Berlin Hbf, will nach Muenchen. Mein ICE 8:05 hat 12 Minuten Verspaetung. Erreiche ich den Anschluss-IC in Nuernberg um 12:33 noch? Falls nicht, was waere die naechste Option? - -### Was FlowMCP macht - -1. **GTFS-SQLite-Lookup** (ueber `geo-gtfs-toolkit` Add-on, lokale DB) — Statischer Fahrplan ICE 8:05 → Anschluss IC 12:33, geplante Umsteigezeit 9 min, Bahnsteig-Layout in Nuernberg. -2. **Live-Verspaetungs-Query** (Deutsche-Bahn-REST-API via FlowMCP-Schema) — Aktueller Ankunfts-Forecast Nuernberg 12:29 (vorher 12:17), Umsteigezeit jetzt 4 min — kritisch. -3. **Alternativen-Suche** (GTFS-SQLite + REST kombiniert) — Naechster IC 13:33 als Backup, Ankunft Muenchen 14:55. -4. **AI-Antwort** — "IC 12:33 mit nur 4 Minuten Umsteigezeit nicht zuverlaessig. Backup: IC 13:33, Ankunft Muenchen 14:55 statt 13:13." - -**Lokale SQLite-DB fuer Static-Lookup + Live-API ueber FlowMCP — ein CLI-Call, eine Antwort.** Ohne FlowMCP muesste der Agent die statische GTFS-Abfrage und die Live-REST-API separat orchestrieren, unterschiedliche Formate parsen und von Hand mergen. - -### Naechste Schritte - -- [GTFS-Pilot-Guide →](/de/guides/gtfs-pilot/) — die volle Mobility-Add-on-Geschichte -- [CLI-Setup →](/de/quickstart/quickstart/) — erster Call in unter 5 Minuten diff --git a/src/content/docs/de/quickstart/quickstart.mdx b/src/content/docs/de/quickstart/quickstart.mdx index c4fe045..dfe7b2b 100644 --- a/src/content/docs/de/quickstart/quickstart.mdx +++ b/src/content/docs/de/quickstart/quickstart.mdx @@ -6,18 +6,12 @@ description: "Erstelle dein erstes FlowMCP-Schema und rufe eine API in 5 Minuten Get Started {/* PAGEFIND-META-END */} -import { Aside } from '@astrojs/starlight/components' import InstallNote from '../../../../components/InstallNote.astro' import refs from '../../../../data/refs.json' export const schemaCount = refs?.stats?.count_schemas ?? '—' export const toolCount = refs?.stats?.count_tools ?? '—' - - ## CLI installieren Die FlowMCP CLI ist der schnellste Weg zu einem funktionierenden Setup. Sie laesst dich den Katalog mit {toolCount} Tools durchsuchen, Schemas hinzufuegen und APIs aufrufen — ohne Code zu schreiben. @@ -48,7 +42,7 @@ Zwei Befehle und du hast einen Live-API-Aufruf — es gibt keinen Aktivierungssc - **npm** — wird mit Node.js ausgeliefert :::note[FlowMCP in eigenen Code einbetten?] -Die CLI ist der schnellste Weg fuer Setup, Hackathons und das Erkunden des Katalogs. Wenn du FlowMCP direkt in eine Node.js-Anwendung einbetten willst — Schemas laden, validieren und APIs programmatisch aufrufen — nutze stattdessen die Core Library. Die vollstaendige Methoden-Referenz, inkl. Betrieb deines Schemas als MCP Server, steht auf der [Programmatic API](/de/reference/core-methods/) Seite. +Die CLI ist der schnellste Weg fuer Setup, Hackathons und das Erkunden des Katalogs. Wenn du FlowMCP direkt in eine Node.js-Anwendung einbetten willst — Schemas laden, validieren und APIs programmatisch aufrufen — nutze stattdessen die Core Library. ::: ## Naechste Schritte @@ -61,10 +55,6 @@ Schreibe dein eigenes Schema fuer eine API, die nicht im Katalog ist. Siehe [Sch Lerne das vollstaendige Schema-Format mit Authentifizierung, Parametern und Handlern. Siehe [Schema-Erstellung](/de/guides/schema-creation/). ::: -:::note[CLI-Referenz] -Suche, liste und rufe {schemaCount} vorgefertigte Schemas von der Kommandozeile auf. Siehe [CLI Usage](/de/reference/cli/). -::: - :::note[Beispiele] Praxisnahe Schema-Beispiele fuer gaengige APIs. Siehe [Beispiele](/de/guides/examples/). ::: diff --git a/src/content/docs/de/quickstart/what-is-flowmcp.mdx b/src/content/docs/de/quickstart/what-is-flowmcp.mdx index e21f7c6..6c4ddd7 100644 --- a/src/content/docs/de/quickstart/what-is-flowmcp.mdx +++ b/src/content/docs/de/quickstart/what-is-flowmcp.mdx @@ -119,7 +119,7 @@ Systemanforderungen und Einrichtungsanweisungen. Siehe [Installation](/de/quicks ::: :::note[CLI-Referenz] -Vollstaendige Befehlsreferenz fuer search, list, call, validate und grading. Siehe [CLI Usage](/de/reference/cli/). +Vollstaendige Befehlsreferenz fuer search, list, call, validate und grading. Siehe [Schnellstart](/de/quickstart/quickstart/). ::: :::note[Schema-Erstellung] diff --git a/src/content/docs/de/reference/cli.mdx b/src/content/docs/de/reference/cli.mdx deleted file mode 100644 index f506020..0000000 --- a/src/content/docs/de/reference/cli.mdx +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: CLI-Nutzung -description: FlowMCP-Tools von der Kommandozeile aus suchen, auflisten und aufrufen ---- -{/* PAGEFIND-META-START */} -Reference -{/* PAGEFIND-META-END */} - -import InstallNote from '../../../../components/InstallNote.astro'; - -:::note[Neu bei FlowMCP?] -Diese Seite ist die vollstaendige CLI-Referenz. Fuer eine gefuehrte Fuenf-Minuten-Installation und deinen ersten Live-API-Aufruf starte mit [CLI Setup](/de/quickstart/quickstart/). -::: - -## Installation - - - -## CLI-Workflow - -Die CLI folgt einem Zwei-Schritte-Muster: Tools entdecken, dann aufrufen. Es gibt keinen Aktivierungsschritt — jedes Tool aus den konfigurierten `schemaFolders[]` ist sofort aufrufbar. - -```mermaid -flowchart TD - A[flowmcp search query] --> B[Browse matching tools + parameters] - B --> E[flowmcp call tool-name JSON-args] - E --> F[Tool result returned] -``` - -## Kernbefehle - -| Befehl | Beschreibung | -|--------|-------------| -| `flowmcp search ` | Tools suchen (max. 10 Ergebnisse), zeigt erforderliche Parameter | -| `flowmcp list` | Alle verfuegbaren Tools anzeigen (mit `disabledCount`) | -| `flowmcp call '{json}'` | Tool mit JSON-Parametern aufrufen | -| `flowmcp status` | Health-Check | - -## Suchen, Auflisten, Aufrufen - -Tools per Stichwort entdecken — die Antwort zeigt die erforderlichen Parameter jedes Tools. Dann das Tool direkt mit JSON-Argumenten aufrufen. Es gibt keinen Aktivierungsschritt: Jedes Tool aus den konfigurierten `schemaFolders[]` ist sofort aufrufbar. Ein Tool, dem ein API-Schluessel fehlt, erscheint als `[disabled: missing KEY]`. - -```bash -flowmcp search ethereum -flowmcp call get_contract_abi_etherscan '{"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"}' -``` - -`flowmcp list` zeigt den vollstaendigen Katalog, inklusive der Anzahl wegen fehlender Schluessel deaktivierter Tools. - -:::note[Programmatische Nutzung] -Fuer programmatischen Zugriff (nicht via CLI) siehe die [Programmatic API](/de/reference/core-methods). -::: - -## Agent-Modus vs Dev-Modus - -Die CLI hat zwei Betriebsmodi, die steuern, welche Befehle verfuegbar sind: - -| Modus | Befehle | Anwendungsfall | -|-------|---------|----------------| -| **Agent** | search, list, call, status | Taeglicher KI-Agent-Einsatz | -| **Dev** | + validate, grading, migrate | Schema-Entwicklung | - -```bash -flowmcp mode dev # In den Dev-Modus wechseln -flowmcp mode agent # Zurueck zum Agent-Modus -``` - -:::note[Standard-Modus] -Agent-Modus ist der Standard. Er stellt nur die Befehle bereit, die ein KI-Agent zum Entdecken und Aufrufen von Tools benoetigt. Wechsle in den Dev-Modus fuer Schema-Entwicklung und Validierungs-Workflows. -::: - -## Dev-Modus-Befehle - -Der Dev-Modus schaltet zusaetzliche Befehle fuer Schema-Autoren frei: - -```bash -flowmcp validate # Schema-Struktur validieren -flowmcp grading deterministic # Strukturvalidierung + Live-Daten-Pretest (Alias: det) -flowmcp grading non-deterministic # LLM-Scoring (Alias: nondet) -flowmcp validate-agent # Agent-Manifest validieren -``` - -## Lokale Projektkonfiguration - -Die CLI liest ihre konfigurierten `schemaFolders[]` aus einem `.flowmcp/`-Verzeichnis in deinem Projekt: - -``` -.flowmcp/ -└── config.json # Konfigurierte schemaFolders[] + Modus -``` - -`config.json` listet die Schema-Ordner, die die CLI laedt. Jedes Tool in diesen Ordnern ist sofort fuer `search`, `list` und `call` verfuegbar — es wird keine Aktivierungsdatei pro Tool geschrieben. - -## API-Schluessel - -:::tip[API-Schluessel-Verwaltung] -Manche Tools benoetigen API-Schluessel, die in `~/.flowmcp/.env` gespeichert werden. Wenn ein `call` wegen fehlender Schluessel fehlschlaegt, fuege den benoetigten Schluessel zur globalen Konfiguration hinzu: - -```bash -echo "ETHERSCAN_API_KEY=your_key_here" >> ~/.flowmcp/.env -``` - -API-Schluessel niemals in die Versionskontrolle committen. Die `.env`-Datei in `~/.flowmcp/` ist dein globaler Schluessel-Speicher und sollte nur auf deinem Rechner bleiben. -::: diff --git a/src/content/docs/de/reference/core-methods.md b/src/content/docs/de/reference/core-methods.md deleted file mode 100644 index f164e92..0000000 --- a/src/content/docs/de/reference/core-methods.md +++ /dev/null @@ -1,637 +0,0 @@ ---- -title: Programmatic API -description: Vollstaendige FlowMCP Core Methoden-Referenz ---- - -Reference - - -Vollstaendige Referenz aller oeffentlichen Methoden in `flowmcp-core`. Methoden sind nach Verwendungskategorie organisiert. Alle Methoden sind statisch. - -```javascript -import { FlowMCP } from 'flowmcp-core' -``` - -:::note -FlowMCP Core exportiert sowohl v3 (Standard) als auch Legacy-APIs. Diese Referenz behandelt die aktuelle v3-API. Fuer v1-Methoden importiere aus `flowmcp-core/v1`. -::: - -## Methodenuebersicht - -| Methode | Zweck | Rueckgabe | -|---------|-------|-----------| -| `.loadSchema()` | Schema-Datei laden und validieren | `{ status, main, handlerMap }` | -| `.validateMain()` | main-Export gegen Validierungsregeln pruefen | `{ status, messages }` | -| `.scanSecurity()` | Sicherheitsscan auf Schema-Datei ausfuehren | `{ status, messages }` | -| `.fetch()` | API-Request fuer ein Tool ausfuehren | `{ status, dataAsString, messages }` | -| `.resolveSharedLists()` | Shared-List-Referenzen aufloesen | `{ sharedLists }` | -| `.interpolateEnum()` | Shared-List-Werte in Enum-Templates interpolieren | `{ result }` | -| `.loadLibraries()` | Deklarierte Libraries aus Allowlist laden | `{ libraries }` | -| `.createHandlers()` | Handler-Map aus Factory-Funktion erstellen | `{ handlerMap }` | -| `.detectLegacy()` | Erkennen, ob ein Modul v1-Format verwendet | `{ isLegacy, format }` | -| `.adaptLegacy()` | v1-Schema in v2-Format konvertieren | `{ main, handlersFn, hasHandlers, warnings }` | -| `.getDefaultAllowlist()` | Standard-Library-Allowlist abrufen | `{ allowlist }` | -| `.generateOutputSchema()` | Output-Schema aus API-Antwort generieren | `{ output }` | - ---- - -## Schema laden und validieren - -### .loadSchema() - -Laedt eine `.mjs`-Schema-Datei, fuehrt Security-Scanning durch, validiert den `main`-Export, loest Shared Lists auf, laedt deklarierte Libraries, erstellt die Handler-Map und verarbeitet Resources und Skills. Dies ist der primaere Einstiegspunkt fuer die Arbeit mit Schemas. - -**Methode** -```javascript -const result = await FlowMCP.loadSchema( { filePath, listsDir, allowlist } ) -``` - -**Parameter** - -| Key | Typ | Beschreibung | Erforderlich | -|-----|-----|-------------|-------------| -| `filePath` | string | Absoluter oder relativer Pfad zur `.mjs`-Schema-Datei | Ja | -| `listsDir` | string | Verzeichnis mit Shared-List-Dateien | Nein | -| `allowlist` | array | Erlaubte Library-Namen fuer Handler. Standard wenn ausgelassen | Nein | - -**Beispiel** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { status, main, handlerMap } = await FlowMCP.loadSchema( { - filePath: './schemas/coingecko-price.mjs' -} ) - -if( !status ) { - console.error( 'Schema loading failed' ) -} - -// Das geladene Schema nutzen -const result = await FlowMCP.fetch( { - main, - handlerMap, - userParams: { id: 'bitcoin' }, - serverParams: {}, - routeName: 'getPrice' -} ) -``` - -**Rueckgabe** -```javascript -{ - status: true, // false wenn Laden, Validierung oder Security-Scan fehlschlagen - main: { ... }, // Das validierte main-Export-Objekt (mit tools, resources, skills) - handlerMap: { ... } // Tool-basierte Handler-Funktionen (leeres Objekt ohne Handler) -} -``` - -### .validateMain() - -Validiert ein `main`-Export-Objekt gegen die FlowMCP-Spezifikation. Fuehrt Validierungsregeln in Kategorien wie Struktur, Benennung, Parameter, Sicherheit, Output-Deklarationen, Resources und Skills aus. - -**Methode** -```javascript -const { status, messages } = FlowMCP.validateMain( { main } ) -``` - -**Parameter** - -| Key | Typ | Beschreibung | Erforderlich | -|-----|-----|-------------|-------------| -| `main` | object | Der `main`-Export aus einer Schema-Datei. Akzeptiert sowohl `tools` als auch `routes` (veralteter Alias) | Ja | - -**Beispiel** -```javascript -import { FlowMCP } from 'flowmcp-core' -import { main } from './schemas/coingecko-price.mjs' - -const { status, messages } = FlowMCP.validateMain( { main } ) - -if( status ) { - console.log( 'Schema is valid' ) -} else { - console.error( 'Validation failed:' ) - messages.forEach( ( msg ) => console.error( ` - ${msg}` ) ) -} -``` - -**Rueckgabe** -```javascript -{ - status: true, // true wenn alle Regeln bestehen - messages: [] // Array mit Fehlermeldungen, wenn status false ist -} -``` - -:::tip -`validateMain()` waehrend der Entwicklung verwenden, um Schema-Fehler frueh zu erkennen. In Produktion `loadSchema()` verwenden, das Validierung als Teil der vollstaendigen Pipeline einschliesst. -::: - -### .scanSecurity() - -Fuehrt einen statischen Sicherheitsscan auf einer Schema-Datei aus. Prueft auf verbotene Muster wie `import`-Statements, `require()`-Aufrufe, Dateisystemzugriff, `eval()` und andere unerlaubte Konstrukte. - -**Methode** -```javascript -const { status, messages } = await FlowMCP.scanSecurity( { filePath } ) -``` - -**Parameter** - -| Key | Typ | Beschreibung | Erforderlich | -|-----|-----|-------------|-------------| -| `filePath` | string | Pfad zur zu scannenden `.mjs`-Schema-Datei | Ja | - -**Beispiel** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { status, messages } = await FlowMCP.scanSecurity( { - filePath: './schemas/my-schema.mjs' -} ) - -if( !status ) { - console.error( 'Security violations found:' ) - messages.forEach( ( msg ) => console.error( ` - ${msg}` ) ) -} -``` - -**Rueckgabe** -```javascript -{ - status: true, // false wenn verbotene Muster erkannt werden - messages: [] // Beschreibungen der Sicherheitsverletzungen -} -``` - ---- - -## Ausfuehrung - -### .fetch() - -Fuehrt einen HTTP-Request fuer ein bestimmtes Tool mit dem geladenen Schema aus. Behandelt Parameter-Substitution, URL-Konstruktion, Header-Injection und optionale Pre/Post-Verarbeitung ueber Handler. - -**Methode** -```javascript -const result = await FlowMCP.fetch( { main, handlerMap, userParams, serverParams, routeName } ) -``` - -**Parameter** - -| Key | Typ | Beschreibung | Erforderlich | -|-----|-----|-------------|-------------| -| `main` | object | Der validierte `main`-Export aus einem Schema | Ja | -| `handlerMap` | object | Handler-Map aus `loadSchema()` oder `createHandlers()` | Ja | -| `userParams` | object | Vom Benutzer bereitgestellte Parameter (KI-Client-Eingabe) | Ja | -| `serverParams` | object | Serverseitige Parameter (API-Schluessel, Tokens) | Ja | -| `routeName` | string | Name des auszufuehrenden Tools | Ja | - -**Beispiel** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { status, main, handlerMap } = await FlowMCP.loadSchema( { - filePath: './schemas/coingecko-price.mjs' -} ) - -const result = await FlowMCP.fetch( { - main, - handlerMap, - userParams: { id: 'bitcoin', vs_currency: 'usd' }, - serverParams: {}, - routeName: 'getPrice' -} ) - -if( result.status ) { - console.log( 'Response:', result.dataAsString ) -} else { - console.error( 'Request failed:', result.messages ) -} -``` - -**Rueckgabe** -```javascript -{ - status: true, // false wenn der Request fehlschlaegt - dataAsString: '{"bitcoin":{"usd":45000}}', // Response-Body als String - messages: [] // Fehlermeldungen, wenn status false ist -} -``` - -:::caution -Das `serverParams`-Objekt sollte API-Schluessel und Secrets enthalten. Diese Werte werden zur Laufzeit in Header und Parameter injiziert, aber niemals KI-Clients offengelegt. -::: - ---- - -## Shared Lists und Abhaengigkeiten - -### .resolveSharedLists() - -Loest Shared-List-Referenzen aus einem Verzeichnis mit List-Dateien auf. Shared Lists sind wiederverwendbare Wertsammlungen (Chain-IDs, Token-Symbole, Protokoll-Namen), die Schemas ueber `$listName`-Syntax in Enum-Parametern referenzieren. - -**Methode** -```javascript -const { sharedLists } = await FlowMCP.resolveSharedLists( { sharedListRefs, listsDir } ) -``` - -**Parameter** - -| Key | Typ | Beschreibung | Erforderlich | -|-----|-----|-------------|-------------| -| `sharedListRefs` | array | Array von Shared-List-Referenzen aus dem Schema | Ja | -| `listsDir` | string | Verzeichnispfad mit Shared-List `.mjs`-Dateien | Ja | - -**Beispiel** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { sharedLists } = await FlowMCP.resolveSharedLists( { - sharedListRefs: [ 'evmChains', 'stablecoins' ], - listsDir: './lists/' -} ) - -console.log( 'Resolved lists:', Object.keys( sharedLists ) ) -// Output: ['evmChains', 'stablecoins'] -``` - -**Rueckgabe** -```javascript -{ - sharedLists: { - evmChains: [ 'ethereum', 'polygon', 'arbitrum', ... ], - stablecoins: [ 'USDT', 'USDC', 'DAI', ... ] - } -} -``` - -### .interpolateEnum() - -Interpoliert Shared-List-Werte in einen Enum-Template-String. Ersetzt `$listName`-Referenzen durch tatsaechliche Werte aus aufgeloesten Shared Lists. - -**Methode** -```javascript -const { result } = FlowMCP.interpolateEnum( { template, sharedLists } ) -``` - -**Parameter** - -| Key | Typ | Beschreibung | Erforderlich | -|-----|-----|-------------|-------------| -| `template` | string | Enum-Template mit `$listName`-Referenzen | Ja | -| `sharedLists` | object | Aufgeloeste Shared Lists aus `resolveSharedLists()` | Ja | - -**Beispiel** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const sharedLists = { - evmChains: [ 'ethereum', 'polygon', 'arbitrum' ] -} - -const { result } = FlowMCP.interpolateEnum( { - template: '$evmChains', - sharedLists -} ) - -console.log( result ) -// Output: ['ethereum', 'polygon', 'arbitrum'] -``` - -**Rueckgabe** -```javascript -{ - result: [ 'ethereum', 'polygon', 'arbitrum' ] // Aufgeloeste Enum-Werte -} -``` - -### .loadLibraries() - -Laedt npm-Pakete, die in `requiredLibraries` eines Schemas deklariert sind. Nur Pakete auf der Allowlist koennen geladen werden. Dies erzwingt das Zero-Import-Sicherheitsmodell. - -**Methode** -```javascript -const { libraries } = await FlowMCP.loadLibraries( { requiredLibraries, allowlist } ) -``` - -**Parameter** - -| Key | Typ | Beschreibung | Erforderlich | -|-----|-----|-------------|-------------| -| `requiredLibraries` | array | Im Schema deklarierte Library-Namen | Ja | -| `allowlist` | array | Erlaubte Library-Namen. `getDefaultAllowlist()` fuer Standardwerte verwenden | Ja | - -**Beispiel** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { allowlist } = FlowMCP.getDefaultAllowlist() - -const { libraries } = await FlowMCP.loadLibraries( { - requiredLibraries: [ 'ethers' ], - allowlist -} ) - -// libraries.ethers ist nun fuer Handler-Injection verfuegbar -``` - -**Rueckgabe** -```javascript -{ - libraries: { - ethers: { ... } // Das geladene Library-Modul - } -} -``` - -### .getDefaultAllowlist() - -Gibt die Standard-Library-Allowlist zurueck. Das sind die npm-Pakete, die Handler ueber Dependency Injection verwenden duerfen. - -**Methode** -```javascript -const { allowlist } = FlowMCP.getDefaultAllowlist() -``` - -**Parameter** - -Keine. - -**Beispiel** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { allowlist } = FlowMCP.getDefaultAllowlist() -console.log( 'Allowed libraries:', allowlist ) -``` - -**Rueckgabe** -```javascript -{ - allowlist: [ 'ethers', 'viem', ... ] // Array erlaubter Library-Namen -} -``` - ---- - -## Handler-Verwaltung - -### .createHandlers() - -Erstellt eine Handler-Map durch Aufruf der `handlers`-Factory-Funktion mit injizierten Abhaengigkeiten. Die resultierende Map ist nach Tool-Name geschluesselt und enthaelt `preProcess`- und `postProcess`-Funktionen. - -**Methode** -```javascript -const { handlerMap } = FlowMCP.createHandlers( { handlersFn, sharedLists, libraries, routeNames } ) -``` - -**Parameter** - -| Key | Typ | Beschreibung | Erforderlich | -|-----|-----|-------------|-------------| -| `handlersFn` | function | Die `handlers`-Factory-Funktion aus einem Schema | Ja | -| `sharedLists` | object | Aufgeloeste Shared Lists fuer die Injection | Ja | -| `libraries` | object | Geladene Libraries fuer die Injection | Ja | -| `routeNames` | array | Erwartete Tool-Namen zur Validierung | Ja | - -**Beispiel** -```javascript -import { FlowMCP } from 'flowmcp-core' -import { handlers } from './schemas/my-schema.mjs' - -const { handlerMap } = FlowMCP.createHandlers( { - handlersFn: handlers, - sharedLists: { evmChains: [ 'ethereum', 'polygon' ] }, - libraries: {}, - routeNames: [ 'getPrice', 'getHistory' ] -} ) - -// handlerMap.getPrice.postProcess ist nun verfuegbar -``` - -**Rueckgabe** -```javascript -{ - handlerMap: { - getPrice: { - postProcess: async ( { data } ) => { ... } - }, - getHistory: { - preProcess: async ( { params } ) => { ... }, - postProcess: async ( { data } ) => { ... } - } - } -} -``` - -:::tip -`createHandlers()` muss selten direkt aufgerufen werden. Die `loadSchema()`-Pipeline behandelt die Handler-Erstellung automatisch. Verwende diese Methode, wenn du manuelle Kontrolle ueber den Dependency-Injection-Prozess benoetigst. -::: - ---- - -## Legacy-Kompatibilitaet - -### .detectLegacy() - -Erkennt, ob ein geladenes Modul das v1-Schema-Format verwendet. Gibt die erkannte Format-Version zurueck. - -**Methode** -```javascript -const { isLegacy, format } = FlowMCP.detectLegacy( { module } ) -``` - -**Parameter** - -| Key | Typ | Beschreibung | Erforderlich | -|-----|-----|-------------|-------------| -| `module` | object | Das importierte Modul aus einer `.mjs`-Schema-Datei | Ja | - -**Beispiel** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const schemaModule = await import( './schemas/old-schema.mjs' ) -const { isLegacy, format } = FlowMCP.detectLegacy( { module: schemaModule } ) - -if( isLegacy ) { - console.log( `Legacy format detected: ${format}` ) - // Mit adaptLegacy() konvertieren -} -``` - -**Rueckgabe** -```javascript -{ - isLegacy: true, // true wenn das Modul v1-Format verwendet - format: 'v1' // Erkannte Format-Version als String -} -``` - -### .adaptLegacy() - -Konvertiert ein v1-Schema-Objekt in das v2-Zwei-Export-Format. Gibt den adaptierten `main`-Export, optionale Handler-Factory-Funktion und Konvertierungswarnungen zurueck. - -**Methode** -```javascript -const { main, handlersFn, hasHandlers, warnings } = FlowMCP.adaptLegacy( { legacySchema } ) -``` - -**Parameter** - -| Key | Typ | Beschreibung | Erforderlich | -|-----|-----|-------------|-------------| -| `legacySchema` | object | Ein Schema-Objekt im v1-Format | Ja | - -**Beispiel** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const oldSchema = { namespace: 'myapi', root: '...', routes: { ... } } -const { main, handlersFn, hasHandlers, warnings } = FlowMCP.adaptLegacy( { - legacySchema: oldSchema -} ) - -if( warnings.length > 0 ) { - console.log( 'Migration warnings:' ) - warnings.forEach( ( w ) => console.log( ` - ${w}` ) ) -} - -// Das adaptierte Schema mit aktuellen Methoden verwenden -const result = await FlowMCP.fetch( { - main, - handlerMap: {}, - userParams: { ... }, - serverParams: {}, - routeName: 'myRoute' -} ) -``` - -**Rueckgabe** -```javascript -{ - main: { ... }, // Konvertierter main-Export - handlersFn: Function|null, // Handler-Factory (null wenn keine Handler) - hasHandlers: false, // Ob das Schema Handler hatte - warnings: [] // Konvertierungswarnungen (veraltete Features etc.) -} -``` - ---- - -## Output-Schema-Generierung - -### .generateOutputSchema() - -Generiert ein Output-Schema aus einer erfassten API-Antwort. Das Output-Schema deklariert die erwartete Antwortstruktur fuer nachgelagerte Konsumenten und Dokumentation. - -**Methode** -```javascript -const { output } = FlowMCP.generateOutputSchema( { response, mimeType } ) -``` - -**Parameter** - -| Key | Typ | Beschreibung | Erforderlich | -|-----|-----|-------------|-------------| -| `response` | string | Roher API-Response-Body | Ja | -| `mimeType` | string | Response-MIME-Typ (z. B. `application/json`) | Ja | - -**Beispiel** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { output } = FlowMCP.generateOutputSchema( { - response: '{"bitcoin":{"usd":45000,"eur":38000}}', - mimeType: 'application/json' -} ) - -console.log( output ) -// { type: 'object', fields: { bitcoin: { type: 'object', fields: { ... } } } } -``` - -**Rueckgabe** -```javascript -{ - output: { - type: 'object', - fields: { ... } // Abgeleitete Feldstruktur aus der Antwort - } -} -``` - -:::tip -Diese Methode waehrend der Schema-Entwicklung verwenden, um den `output`-Block fuer deine Tools automatisch zu generieren. Eine echte API-Antwort mit `fetch()` erfassen, dann an `generateOutputSchema()` uebergeben. -::: - ---- - -## v1 API (Legacy) - -Die v1-API ist weiterhin fuer Rueckwaertskompatibilitaet verfuegbar. Separat importieren: - -```javascript -import { v1 } from 'flowmcp-core' -const { FlowMCP } = v1 -``` - -
-v1-Methodenuebersicht - -Die v1-API verwendet ein flaches Schema-Format (Einzelexport) mit anderen Methoden-Signaturen. - -| Methode | v1-Signatur | Aktuelles Aequivalent | -|--------|-------------|---------------| -| `.validateSchema()` | `FlowMCP.validateSchema( { schema } )` | `.validateMain( { main } )` | -| `.fetch()` | `FlowMCP.fetch( { schema, userParams, serverParams, routeName } )` | `.fetch( { main, handlerMap, ... } )` | -| `.activateServerTools()` | `FlowMCP.activateServerTools( { server, schema, serverParams } )` | MCP-SDK direkt mit `.loadSchema()` verwenden | -| `.activateServerTool()` | `FlowMCP.activateServerTool( { server, schema, routeName, serverParams } )` | MCP-SDK direkt verwenden | -| `.prepareServerTool()` | `FlowMCP.prepareServerTool( { schema, serverParams, routeName } )` | `.loadSchema()` + `.fetch()` verwenden | -| `.filterArrayOfSchemas()` | `FlowMCP.filterArrayOfSchemas( { arrayOfSchemas, ... } )` | Gleich (nur v1) | -| `.getArgvParameters()` | `FlowMCP.getArgvParameters( { argv } )` | Gleich (nur v1) | -| `.getZodInterfaces()` | `FlowMCP.getZodInterfaces( { schema } )` | Zod-Schemas werden waehrend `.loadSchema()` generiert | -| `.getAllTests()` | `FlowMCP.getAllTests( { schema } )` | Testwerte stehen in den `test`-Feldern der Parameter | - -:::caution -Die v1-API wird fuer Rueckwaertskompatibilitaet gepflegt, erhaelt aber keine neuen Features. Alle neuen Schemas sollten das v3-Format verwenden. -::: - -
- ---- - -## Typischer Workflow - -Der Standard-Workflow fuer die Nutzung von FlowMCP Core kombiniert diese Methoden: - -```javascript -import { FlowMCP } from 'flowmcp-core' - -// 1. Schema laden (validiert, scannt Sicherheit, loest Listen auf, erstellt Handler) -const { status, main, handlerMap } = await FlowMCP.loadSchema( { - filePath: './schemas/coingecko-price.mjs' -} ) - -if( !status ) { - throw new Error( 'Schema loading failed' ) -} - -// 2. Tool ausfuehren -const result = await FlowMCP.fetch( { - main, - handlerMap, - userParams: { id: 'bitcoin' }, - serverParams: { API_KEY: process.env.COINGECKO_KEY }, - routeName: 'getPrice' -} ) - -// 3. Ergebnis verwenden -if( result.status ) { - console.log( 'Price data:', result.dataAsString ) -} else { - console.error( 'Errors:', result.messages ) -} -``` - -Fuer MCP-Server-Integration siehe den [Server-Integration-Guide](/de/guides/server-integration). diff --git a/src/content/docs/de/reference/mcp-server.md b/src/content/docs/de/reference/mcp-server.md deleted file mode 100644 index e4c1d00..0000000 --- a/src/content/docs/de/reference/mcp-server.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: MCP Server Mode -description: FlowMCP als MCP-Server betreiben fuer die Integration mit Claude Desktop, Cursor und anderen KI-Tools ---- - -Reference - - - -## Was ist MCP? - -Das **Model Context Protocol (MCP)** ist ein offener Standard zur Verbindung von KI-Modellen mit externen Tools und Datenquellen. FlowMCP kann als MCP-Server laufen und alle aktiven Schemas als Tools fuer jeden MCP-kompatiblen KI-Client bereitstellen. - -Anstatt fuer jede API eigenen Server-Code zu schreiben, deklarierst du Schemas und FlowMCP uebernimmt das MCP-Protokoll, die Parameter-Validierung und die API-Ausfuehrung. - -## Architektur - -So verbindet FlowMCP KI-Clients und APIs: - -Der KI-Client sendet Tool-Aufrufe ueber das MCP-Protokoll. FlowMCP loest das richtige Schema auf, validiert Parameter, ruft die Upstream-API auf und gibt das Ergebnis zurueck. - -## Server starten - -Der schnellste Weg, Schemas bereitzustellen, ist ueber die CLI: - -```bash -# Alle aktiven Tools als MCP-Server bereitstellen (stdio) -flowmcp run - -# Eine bestimmte Gruppe bereitstellen -flowmcp run --group crypto -``` - -Fuer programmatische Kontrolle siehe den [Server-Integration-Guide](/de/guides/server-integration). - -## Client-Integration - -### Claude Desktop - -FlowMCP zur `claude_desktop_config.json` hinzufuegen: - -```json -{ - "mcpServers": { - "flowmcp": { - "command": "npx", - "args": ["-y", "flowmcp", "run"], - "env": { - "ETHERSCAN_API_KEY": "your_key_here", - "MORALIS_API_KEY": "your_key_here" - } - } - } -} -``` - -Speicherort der Konfigurationsdatei: -- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - -:::tip -Nach dem Bearbeiten der Konfiguration Claude Desktop neu starten, um die neue MCP-Server-Konfiguration zu uebernehmen. -::: - -### Cursor - -FlowMCP zu den Cursor-MCP-Einstellungen hinzufuegen: - -```json -{ - "mcpServers": { - "flowmcp": { - "command": "npx", - "args": ["-y", "flowmcp", "run"] - } - } -} -``` - -Cursor-Einstellungen oeffnen und zum MCP-Bereich navigieren, um diese Konfiguration hinzuzufuegen. - -### Claude Code - -FlowMCP als lokalen MCP-Server hinzufuegen: - -```bash -claude mcp add flowmcp --scope local -- npx -y flowmcp run -``` - -Claude Code startet den Server automatisch bei Bedarf. - -## Umgebungsvariablen - -API-Schluessel, die von deinen Schemas benoetigt werden, koennen auf drei Wegen bereitgestellt werden: - -| Methode | Beispiel | Geeignet fuer | -|---------|---------|---------------| -| `~/.flowmcp/.env`-Datei | `ETHERSCAN_API_KEY=abc123` | Dauerhaftes lokales Setup | -| `env`-Block in Client-Config | Siehe Claude-Desktop-Beispiel oben | Konfiguration pro Client | -| System-Umgebungsvariablen | `export ETHERSCAN_API_KEY=abc123` | CI/CD und Container | - -:::note[Sicherheit] -API-Schluessel werden zur Laufzeit als Server-Parameter injiziert und sind niemals dem KI-Client zugaenglich. Sie werden nur verwendet, wenn FlowMCP die Upstream-API im Auftrag der KI aufruft. -::: - -## Was wird bereitgestellt - -Alle aktiven Tools aus deiner `.flowmcp/config.json` werden zu MCP-Primitiven: - -| Schema-Primitiv | MCP-Primitiv | Beschreibung | -|-----------------|--------------|-------------| -| Tools | MCP Tools | API-Endpunkte, die die KI aufrufen kann | -| Resources | MCP Resources | Statische Daten, die die KI lesen kann | -| Prompts | MCP Prompts | Vorgefertigte Prompt-Templates | - -Jedes Tool wird mit Name, Beschreibung und Zod-validiertem Parameter-Schema registriert -- der KI-Client erhaelt alles, was er zum Entdecken und Aufrufen des Tools braucht. - -## Naechste Schritte - -:::note[Server-Integration] -Fuer programmatisches Server-Setup mit stdio und HTTP/SSE-Transporten siehe den [Server-Integration-Guide](/de/guides/server-integration). -::: diff --git a/src/content/docs/de/schemas-and-sources.md b/src/content/docs/de/schemas-and-sources.md deleted file mode 100644 index 2c43580..0000000 --- a/src/content/docs/de/schemas-and-sources.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Schemas & Quellen -description: Die drei Schichten von FlowMCP — Engine, Schemas und Datenbetreiber — und warum FlowMCP Schemas weder publiziert noch anzeigt. ---- - -About - - -FlowMCP besteht aus drei Schichten, die leicht zu verwechseln sind, aber strikt getrennt bleiben. Sie auseinanderzuhalten ist der Schluessel zum Verstaendnis, wofuer FlowMCP verantwortlich ist und wofuer nicht. - -## Engine, Schemas und Datenbetreiber - -Die **Engine** ist der Teil, den FlowMCP baut und pflegt. Sie ist die Core-Bibliothek und die CLI, die ein Schema laden, die Anfrage signieren, die Quelle aufrufen und die Antwort normalisieren. Die Engine ist MIT-lizenziert, Open Source, und derselbe Audit deckt jeden Call ab, der durch sie laeuft. - -Ein **Schema** ist eine duenne Deklaration, die der Engine sagt, wie sie eine Datenquelle erreicht und wie sie deren Antwort formt. Schemas sind Community-Beitraege: jede:r kann eines fuer eine API oder einen Datensatz schreiben. Sie sind nicht Teil der Engine, und ein Schema kann hinzugefuegt, ersetzt oder entfernt werden, ohne die Engine anzufassen. - -Ein **Datenbetreiber** ist, wer die API betreibt oder den Datensatz hinter einem Schema publiziert. Er entscheidet ueber seine eigenen Terms of Service, die Daten-Lizenz und die Rate-Limits. FlowMCP hat keine Kontrolle ueber diese Schicht — es reicht den Call nur durch und gibt die Antwort zurueck. - -Diese drei Schichten verschmelzen nie. Die Engine bewegt Daten, Schemas beschreiben Quellen, und Betreiber besitzen die Daten. Sie zu verwechseln ist die haeufigste Quelle von Missverstaendnissen darueber, was FlowMCP tut. - -## Was FlowMCP nicht tut - -FlowMCP **publiziert keine Schemas und zeigt keine Schemas auf dieser Website.** Es gibt hier keine Katalog-Seite, keinen Schema-Browser und keine gehostete Liste von Quellen. Schemas liegen in eigenen Repositories und werden von der CLI bei Bedarf geladen; die Website erklaert die Engine und das Modell, nicht die einzelnen Schemas. - -Weil die Datenbetreiber die Quelle und ihre Bedingungen besitzen, faellt FlowMCP auch kein Urteil darueber. Wir halten einige neutrale Fakten fest, sofern ein Provider sie publiziert — die Terms-of-Service-URL (`meta.termsOfService`), das Datum der letzten Pruefung (`meta.termsOfServiceCheckedAt`) und den Daten-Lizenznamen, sofern einer genannt ist (`meta.dataLicenseName`) — und verlinken auf das Original. Wir klassifizieren diese Bedingungen nicht, interpretieren sie nicht und beraten nicht zur kommerziellen Nutzung. Die Pruefung der Terms of Service, Rate-Limits und Daten-Lizenz eines Providers, bevor du dich auf eine Quelle verlaesst, bleibt deine Verantwortung, und FlowMCP gibt keine Gewaehrleistung fuer Eignung zu irgendeinem Zweck. - -## Siehe auch - -- [Spezifikation: License & ToS (spec/v4.1.0/23-license-and-tos.md)](https://github.com/FlowMCP/flowmcp-spec/blob/main/spec/v4.1.0/23-license-and-tos.md) -- [DISCLAIMER.md in flowmcp-core](https://github.com/FlowMCP/flowmcp-core/blob/main/DISCLAIMER.md) -- [DISCLAIMER.md in flowmcp-cli](https://github.com/FlowMCP/flowmcp-cli/blob/main/DISCLAIMER.md) diff --git a/src/content/docs/ecosystem/agentprobe.md b/src/content/docs/ecosystem/agentprobe.md deleted file mode 100644 index aaa9347..0000000 --- a/src/content/docs/ecosystem/agentprobe.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: AgentProbe -description: Multi-protocol validation for MCP servers, A2A agents, and x402 endpoints ---- - -Ecosystem - - -:::caution[Experimental — Read First] -**Note on x402:** AgentProbe validates endpoints that may use x402. The x402 protocol itself is experimental — read the four points below before relying on its results. - -**What x402 is:** A machine-readable payment protocol based on HTTP status code 402 (Payment Required). It allows API endpoints — including MCP tools — to signal payment requirements and accept payment receipts in a standardized way. - -**Why it is experimental:** The x402 specification, network support (Base, Solana, Stacks), and reference implementations are still evolving in 2026. There is no Service-Level Agreement, no production-grade reliability guarantee, and the wire format may change between minor versions. - -**When to use it:** Hackathon demos, payment-gated MCP tool prototypes, proof-of-concepts, research scenarios. Suitable for closed-loop testing with known clients. - -**What it is not:** Not a production payment gateway. Not a replacement for established PSPs (Stripe, PayPal). Not a compliance-certified payment system. Do not route real customer revenue through this stack without additional safeguards. -::: - -[AgentProbe](https://github.com/FlowMCP/mcp-agent-validator) is a web-based multi-protocol validator for AI agent endpoints. Enter a URL and get instant assessment across eight protocol layers. - -**Live demo:** [agentprobe.xyz](https://agentprobe.xyz) - -## What It Does - -- **Input:** A single agent endpoint URL -- **Assessment:** Runs the `mcp-agent-assessment` pipeline with protocol-specific validators -- **Output:** Unified verdicts per protocol layer plus raw assessment data - -One URL is enough. AgentProbe discovers which protocols the endpoint supports and validates each one independently. - -## Protocol Layers - -AgentProbe assesses eight protocol layers: - -| Layer | What it checks | -|-------|---------------| -| **HTTP** | Connectivity, HTTPS, SSL validation, CORS, HTTP/2 detection | -| **MCP** | Server discovery, tool/resource/prompt listing, capability detection | -| **A2A / AP2** | Agent card validation, AP2 version and role detection via `capabilities.extensions` and `X-A2A-Extensions` header | -| **x402** | Payment-required endpoint detection with scheme, network, and token analysis | -| **OAuth** | Authorization server metadata discovery | -| **MCP Apps** | UI resource detection for MCP applications | -| **HTML** | Website detection, Content-Type, SSL status, HTTP/2 | -| **ERC-8004** | On-chain agent registry lookup with OASF classification, reputation, and metadata extraction | - -:::note -Not every endpoint supports all protocols. AgentProbe gracefully handles unsupported layers and shows results only for detected protocols. -::: - -## Architecture - -```mermaid -flowchart TD - U[URL Input] --> S[Server] --> A[mcp-agent-assessment] - A --> H[HTTP] - A --> M[MCP] - A --> AP[A2A / AP2] - A --> X[x402] - A --> O[OAuth] - H --> R[Results UI] - M --> R - AP --> R - X --> R - O --> R -``` - -The server receives a URL, passes it to the unified assessment pipeline, and returns structured results for each protocol layer. - -## API Endpoints - -### `POST /api/validate` - -Returns a structured validation result with separate sections for each protocol. - -```bash -curl -X POST https://agentprobe.xyz/api/validate \ - -H 'Content-Type: application/json' \ - -d '{"url": "https://your-endpoint.example.com/mcp"}' -``` - -The response contains `mcp`, `a2a`, `ui` (MCP Apps), and `oauth` objects, each with `status`, `categories`, `summary`, and `messages`. - -### `POST /api/assess` - -Returns the raw assessment result from `mcp-agent-assessment` with full layer details. - -```bash -curl -X POST https://agentprobe.xyz/api/assess \ - -H 'Content-Type: application/json' \ - -d '{"url": "https://your-endpoint.example.com/mcp"}' -``` - -Optional parameters: - -| Key | Type | Description | -|-----|------|-------------| -| `timeout` | number | Timeout in milliseconds | -| `erc8004` | object | ERC-8004 config with `rpcNodes` | - -### `POST /api/lookup` - -Query the ERC-8004 on-chain registry for agent registration data, endpoints, OASF classification, and reputation. - -```bash -curl -X POST https://agentprobe.xyz/api/lookup \ - -H 'Content-Type: application/json' \ - -d '{"agentId": 2340, "chainId": 8453}' -``` - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `agentId` | number | Agent token ID in the ERC-8004 registry | Yes | -| `chainId` | number or string | Chain ID (e.g., `8453` for Base) or CAIP-2 (e.g., `eip155:8453`) | Yes | -| `rpcNodes` | object | Custom RPC nodes per chain alias | No | - -## Validate Your Own MCP Server - -1. **Deploy your MCP server** - - Make sure your MCP server is publicly accessible (e.g., via ngrok or a cloud deployment). - -2. **Open AgentProbe** - - Go to [agentprobe.xyz](https://agentprobe.xyz) in your browser. - -3. **Enter your endpoint URL** - - Paste your MCP server URL (e.g., `https://your-server.example.com/mcp`) and click validate. - -4. **Review results** - - AgentProbe shows verdicts for each protocol layer. Green means supported and valid, red means issues detected, gray means not applicable. - -Or use the API directly: - -```bash -curl -X POST https://agentprobe.xyz/api/validate \ - -H 'Content-Type: application/json' \ - -d '{"url": "https://your-server.example.com/mcp"}' -``` - -## Authentication - -Authentication is optional. When `API_TOKEN` is not set, the API is open (dev mode). - -When `API_TOKEN` is set, two authentication methods are supported: - -| Method | How it works | -|--------|-------------| -| **Session Cookie** | Browser visits the UI and receives a session cookie automatically | -| **Bearer Token** | External scripts send `Authorization: Bearer ` header | - -```bash -# With Bearer token -curl -X POST https://agentprobe.xyz/api/validate \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer your-token-here' \ - -d '{"url": "https://your-endpoint.example.com"}' -``` - -## Dependencies - -AgentProbe builds on the FlowMCP validator ecosystem: - -| Package | Purpose | -|---------|---------| -| [mcp-agent-assessment](https://github.com/FlowMCP/mcp-server-assessment) | Unified assessment pipeline | -| [a2a-agent-validator](https://github.com/FlowMCP/a2a-agent-validator) | A2A agent card and AP2 detection | -| [x402-mcp-validator](https://github.com/FlowMCP/x402-mcp-validator) | x402 payment protocol validation | -| [mcp-apps-validator](https://github.com/FlowMCP/mcp-apps-validator) | MCP Apps UI resource detection | -| [erc8004-registry-parser](https://github.com/FlowMCP/erc8004-registry-parser) | ERC-8004 on-chain registry parsing | - -## Links - -- **Live Demo**: [agentprobe.xyz](https://agentprobe.xyz) -- **GitHub**: [FlowMCP/mcp-agent-validator](https://github.com/FlowMCP/mcp-agent-validator) -- **Video**: [Watch on YouTube](https://www.youtube.com/watch?v=gnmsCEly3fA) -- **DoraHacks**: [dorahacks.io/buidl/39293](https://dorahacks.io/buidl/39293) diff --git a/src/content/docs/ecosystem/x402.mdx b/src/content/docs/ecosystem/x402.mdx deleted file mode 100644 index 1087da1..0000000 --- a/src/content/docs/ecosystem/x402.mdx +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: x402 Payment Protocol -description: Add payment-gated access to MCP tools ---- -{/* PAGEFIND-META-START */} -Ecosystem -{/* PAGEFIND-META-END */} - -import InstallNote from '../../../components/InstallNote.astro'; - -:::caution[Experimental — Read First] -**What x402 is:** A machine-readable payment protocol based on HTTP status code 402 (Payment Required). It allows API endpoints — including MCP tools — to signal payment requirements and accept payment receipts in a standardized way. - -**Why it is experimental:** The x402 specification, network support (Base, Solana, Stacks), and reference implementations are still evolving in 2026. There is no Service-Level Agreement, no production-grade reliability guarantee, and the wire format may change between minor versions. - -**When to use it:** Hackathon demos, payment-gated MCP tool prototypes, proof-of-concepts, research scenarios. Suitable for closed-loop testing with known clients. - -**What it is not:** Not a production payment gateway. Not a replacement for established PSPs (Stripe, PayPal). Not a compliance-certified payment system. Do not route real customer revenue through this stack without additional safeguards. -::: - -The [x402 protocol](https://www.x402.org/) brings HTTP status code 402 (Payment Required) to life as a machine-readable payment protocol for APIs. The [x402-mcp-validator](https://github.com/FlowMCP/x402-mcp-validator) validates MCP servers for x402 compliance -- connecting to servers, discovering tools, probing for payment requirements, and validating payment options against the spec. - -## How x402 Works with MCP - -When an MCP tool requires payment, the flow is: - -1. **Client calls a tool** on the MCP server -2. **Server responds with 402** including payment requirements (scheme, network, amount, asset, payTo) -3. **Client processes payment** through the specified payment network -4. **Client retries the tool call** with a payment receipt in the header -5. **Server validates payment** and executes the tool - -This enables API monetization at the tool level -- different tools can have different prices, and free tools can coexist with paid ones on the same server. - -## x402 MCP Validator - -The validator connects to an MCP server end-to-end and returns a structured snapshot: - -```javascript -import { McpServerValidator } from 'x402-mcp-validator' - -const { status, messages, categories, entries } = await McpServerValidator.start( { - endpoint: 'https://your-mcp-server.example.com/mcp', - timeout: 15000 -} ) - -console.log( `Status: ${status ? 'PASS' : 'FAIL'}` ) -console.log( `Tools: ${entries['tools'].length}` ) -console.log( `x402: ${categories['supportsX402']}` ) -console.log( `Networks: ${JSON.stringify( entries['x402']['networks'] )}` ) -``` - -### `.start()` - -Connects to an MCP server, discovers capabilities, probes for x402 payment support, validates payment requirements, measures latency, and returns a structured snapshot. - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `endpoint` | string | MCP server URL | Yes | -| `timeout` | number | Connection timeout in ms (default `10000`) | No | - -**Returns:** `{ status, messages, categories, entries }` - -### `.compare()` - -Compares two snapshots from `.start()` and returns a structured diff with added, removed, and modified items per section. - -```javascript -const before = await McpServerValidator.start( { endpoint: 'https://server.example.com/mcp' } ) -// ... time passes, server changes ... -const after = await McpServerValidator.start( { endpoint: 'https://server.example.com/mcp' } ) - -const { status, messages, hasChanges, diff } = McpServerValidator.compare( { before, after } ) - -console.log( `Changes detected: ${hasChanges}` ) -console.log( `Tools added: ${diff['tools']['added'].length}` ) -console.log( `Tools removed: ${diff['tools']['removed'].length}` ) -``` - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `before` | object | Snapshot from a previous `.start()` call | Yes | -| `after` | object | Snapshot from a later `.start()` call | Yes | - -**Returns:** `{ status, messages, hasChanges, diff }` - -## Categories - -The validator classifies each server with 12 boolean flags: - -| Flag | Description | -|------|-------------| -| `isReachable` | Server responded to HEAD request | -| `supportsMcp` | MCP handshake completed | -| `hasTools` | Server exposes at least one tool | -| `hasResources` | Server exposes at least one resource | -| `hasPrompts` | Server exposes at least one prompt | -| `supportsX402` | At least one tool returned a 402 payment error | -| `hasValidPaymentRequirements` | At least one payment option passed validation | -| `supportsExactScheme` | Has payment options with `scheme: 'exact'` | -| `supportsEvm` | Has payment options with `network: 'eip155:*'` | -| `supportsSolana` | Has payment options with `network: 'solana:*'` | -| `supportsTasks` | Server advertises tasks capability | -| `supportsMcpApps` | Server advertises mcpApps capability | - -## Validation Pipeline - -The validator processes an MCP server in six sequential steps: - -1. **Connect** -- Connects to the MCP server via StreamableHTTP with SSE fallback. -2. **Discover** -- Discovers tools, resources, prompts, and capabilities through MCP protocol. -3. **Classify** -- Classifies server capabilities into the 12 boolean categories. -4. **Probe** -- Probes each tool for x402 payment requirements (HTTP 402 / JSON-RPC -32402). -5. **Validate** -- Validates payment options: scheme, network, amount, asset, payTo, checksums. -6. **Build Snapshot** -- Builds the structured snapshot with categories, entries, and validation messages. - -## Validation Codes - -The validator uses structured error codes organized by category: - -
-VAL -- Input Validation - -Codes `VAL-001` through `VAL-015` cover input parameter validation for both `.start()` and `.compare()` methods. Examples: missing endpoint, invalid URL format, missing snapshots for comparison. -
- -
-CON -- MCP Connection - -Codes `CON-001` through `CON-011` cover server connectivity and MCP handshake issues. Examples: server not reachable, handshake failed, tools/list request failed. -
- -
-PAY -- Payment Validation - -Codes `PAY-001` through `PAY-102` cover x402 payment requirement validation in detail. Checks include: x402 version, resource format, accepts array, scheme, network prefix, amount format, asset address, payTo address with checksum validation, and timeout values. -
- -
-PRB -- Probe - -Codes `PRB-004` and `PRB-005` cover probe-level issues like unexpected exceptions and no tools available. -
- -
-AUTH -- OAuth - -Codes `AUTH-002` through `AUTH-011` cover OAuth discovery including metadata, PKCE support, protected resource metadata, client registration, and scope detection. -
- -
-CMP -- Comparison - -Codes `CMP-001` through `CMP-003` cover snapshot comparison integrity: different server endpoints, missing timestamps, and chronological ordering. -
- -:::tip -Each validation message includes an error code, severity (ERROR, WARNING, INFO), and a human-readable description. Use the codes to programmatically identify and handle specific issues. -::: - -## Links - -- **GitHub**: [FlowMCP/x402-mcp-validator](https://github.com/FlowMCP/x402-mcp-validator) -- **x402 Spec**: [x402.org](https://www.x402.org/) - - diff --git a/src/content/docs/grading/about-convention.md b/src/content/docs/grading/about-convention.md index 3fad76b..40c5e43 100644 --- a/src/content/docs/grading/about-convention.md +++ b/src/content/docs/grading/about-convention.md @@ -6,16 +6,13 @@ spec_file: "11-about-convention.md" order: 11 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/11-about-convention.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/11-about-convention.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/11-about-convention.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/11-about-convention.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/default-journey.md b/src/content/docs/grading/default-journey.md index 36ede3a..7b0cbfd 100644 --- a/src/content/docs/grading/default-journey.md +++ b/src/content/docs/grading/default-journey.md @@ -6,16 +6,13 @@ spec_file: "01-default-journey.md" order: 1 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/01-default-journey.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/01-default-journey.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/01-default-journey.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/01-default-journey.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification. diff --git a/src/content/docs/grading/determinism-and-tier.md b/src/content/docs/grading/determinism-and-tier.md index 5d827dc..4f5e0ea 100644 --- a/src/content/docs/grading/determinism-and-tier.md +++ b/src/content/docs/grading/determinism-and-tier.md @@ -6,16 +6,13 @@ spec_file: "06-determinism-and-tier.md" order: 6 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/06-determinism-and-tier.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/06-determinism-and-tier.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/06-determinism-and-tier.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/06-determinism-and-tier.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/domain-knowledge.md b/src/content/docs/grading/domain-knowledge.md index c604515..92c0a22 100644 --- a/src/content/docs/grading/domain-knowledge.md +++ b/src/content/docs/grading/domain-knowledge.md @@ -6,16 +6,13 @@ spec_file: "10-domain-knowledge.md" order: 10 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/10-domain-knowledge.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/10-domain-knowledge.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/10-domain-knowledge.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/10-domain-knowledge.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/eligibility.md b/src/content/docs/grading/eligibility.md index 1ebc634..4c2111a 100644 --- a/src/content/docs/grading/eligibility.md +++ b/src/content/docs/grading/eligibility.md @@ -6,16 +6,13 @@ spec_file: "02-eligibility.md" order: 2 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/02-eligibility.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/02-eligibility.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/02-eligibility.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/02-eligibility.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification. diff --git a/src/content/docs/grading/entry-point-prompt.md b/src/content/docs/grading/entry-point-prompt.md index e8713e8..c0b4d4a 100644 --- a/src/content/docs/grading/entry-point-prompt.md +++ b/src/content/docs/grading/entry-point-prompt.md @@ -6,16 +6,13 @@ spec_file: "20-entry-point-prompt.md" order: 20 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/20-entry-point-prompt.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/20-entry-point-prompt.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/20-entry-point-prompt.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/20-entry-point-prompt.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/flywheel-loop.md b/src/content/docs/grading/flywheel-loop.md index 4102b8f..c52d248 100644 --- a/src/content/docs/grading/flywheel-loop.md +++ b/src/content/docs/grading/flywheel-loop.md @@ -6,16 +6,13 @@ spec_file: "18-flywheel-loop.md" order: 18 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/18-flywheel-loop.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/18-flywheel-loop.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/18-flywheel-loop.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/18-flywheel-loop.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/folder-layout.md b/src/content/docs/grading/folder-layout.md index 9b2f6e3..7715fa0 100644 --- a/src/content/docs/grading/folder-layout.md +++ b/src/content/docs/grading/folder-layout.md @@ -6,16 +6,13 @@ spec_file: "19-folder-layout.md" order: 19 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/19-folder-layout.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/19-folder-layout.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/19-folder-layout.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/19-folder-layout.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/grading-model.md b/src/content/docs/grading/grading-model.md index 871cdd1..191d825 100644 --- a/src/content/docs/grading/grading-model.md +++ b/src/content/docs/grading/grading-model.md @@ -6,16 +6,13 @@ spec_file: "08-grading-model.md" order: 8 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/08-grading-model.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/08-grading-model.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/08-grading-model.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/08-grading-model.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/harness-and-goal.md b/src/content/docs/grading/harness-and-goal.md index 61c0432..72bf27f 100644 --- a/src/content/docs/grading/harness-and-goal.md +++ b/src/content/docs/grading/harness-and-goal.md @@ -6,16 +6,13 @@ spec_file: "25-harness-and-goal.md" order: 25 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/25-harness-and-goal.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/25-harness-and-goal.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/25-harness-and-goal.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/25-harness-and-goal.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). diff --git a/src/content/docs/grading/index-json.md b/src/content/docs/grading/index-json.md index 1fd9470..d377a75 100644 --- a/src/content/docs/grading/index-json.md +++ b/src/content/docs/grading/index-json.md @@ -6,16 +6,13 @@ spec_file: "23-index-json.md" order: 23 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/23-index-json.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/23-index-json.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/23-index-json.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/23-index-json.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). diff --git a/src/content/docs/grading/kanban-data-contract.md b/src/content/docs/grading/kanban-data-contract.md index fc238b2..faa4087 100644 --- a/src/content/docs/grading/kanban-data-contract.md +++ b/src/content/docs/grading/kanban-data-contract.md @@ -6,16 +6,13 @@ spec_file: "14-kanban-data-contract.md" order: 14 section: "Grading" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/14-kanban-data-contract.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/14-kanban-data-contract.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/14-kanban-data-contract.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/14-kanban-data-contract.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). diff --git a/src/content/docs/grading/monitoring-track.md b/src/content/docs/grading/monitoring-track.md index b97694d..6cff9df 100644 --- a/src/content/docs/grading/monitoring-track.md +++ b/src/content/docs/grading/monitoring-track.md @@ -6,16 +6,13 @@ spec_file: "26-monitoring-track.md" order: 26 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/26-monitoring-track.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/26-monitoring-track.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/26-monitoring-track.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/26-monitoring-track.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/overview.md b/src/content/docs/grading/overview.md index c28fd3f..f2cbd37 100644 --- a/src/content/docs/grading/overview.md +++ b/src/content/docs/grading/overview.md @@ -6,16 +6,13 @@ spec_file: "00-overview.md" order: 0 section: "Grading" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/00-overview.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/00-overview.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/00-overview.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/00-overview.md." --- - The Grading-Spec describes **how** FlowMCP schemas and selections are evaluated and graded — the phases, the Scoring System, the Grading System, the categorical veto, tiers, skills, and domain knowledge. It is a separate, independently versioned document layered on top of the FlowMCP Schemas Specification, which remains the highest authority for what a schema, a selection, and the primitives actually are. This overview sets the conformance language, the document hierarchy, the guiding interoperability focus, and the chapter map for the rest of the spec. diff --git a/src/content/docs/grading/personas-contract.md b/src/content/docs/grading/personas-contract.md index 5892355..f895659 100644 --- a/src/content/docs/grading/personas-contract.md +++ b/src/content/docs/grading/personas-contract.md @@ -6,16 +6,13 @@ spec_file: "12-personas-contract.md" order: 12 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/12-personas-contract.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/12-personas-contract.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/12-personas-contract.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/12-personas-contract.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/phases-selection.md b/src/content/docs/grading/phases-selection.md index 7fb5197..73ab2f3 100644 --- a/src/content/docs/grading/phases-selection.md +++ b/src/content/docs/grading/phases-selection.md @@ -6,16 +6,13 @@ spec_file: "05-phases-selection.md" order: 5 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/05-phases-selection.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/05-phases-selection.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/05-phases-selection.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/05-phases-selection.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/phases-single.md b/src/content/docs/grading/phases-single.md index 2cc6e25..5632706 100644 --- a/src/content/docs/grading/phases-single.md +++ b/src/content/docs/grading/phases-single.md @@ -6,16 +6,13 @@ spec_file: "04-phases-single.md" order: 4 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/04-phases-single.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/04-phases-single.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/04-phases-single.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/04-phases-single.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification. diff --git a/src/content/docs/grading/pre-conditions.md b/src/content/docs/grading/pre-conditions.md index df0bbd6..664ca43 100644 --- a/src/content/docs/grading/pre-conditions.md +++ b/src/content/docs/grading/pre-conditions.md @@ -6,16 +6,13 @@ spec_file: "21-pre-conditions.md" order: 21 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/21-pre-conditions.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/21-pre-conditions.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/21-pre-conditions.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/21-pre-conditions.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/scope-whitelist.md b/src/content/docs/grading/scope-whitelist.md index 37bf23f..81872b9 100644 --- a/src/content/docs/grading/scope-whitelist.md +++ b/src/content/docs/grading/scope-whitelist.md @@ -6,16 +6,13 @@ spec_file: "17-scope-whitelist.md" order: 17 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/17-scope-whitelist.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/17-scope-whitelist.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/17-scope-whitelist.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/17-scope-whitelist.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/scoring-vs-grading.md b/src/content/docs/grading/scoring-vs-grading.md index 6791df8..dd97b83 100644 --- a/src/content/docs/grading/scoring-vs-grading.md +++ b/src/content/docs/grading/scoring-vs-grading.md @@ -6,16 +6,13 @@ spec_file: "07-scoring-vs-grading.md" order: 7 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/07-scoring-vs-grading.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/07-scoring-vs-grading.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/07-scoring-vs-grading.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/07-scoring-vs-grading.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/security-and-development.md b/src/content/docs/grading/security-and-development.md index 54f7178..85cbba2 100644 --- a/src/content/docs/grading/security-and-development.md +++ b/src/content/docs/grading/security-and-development.md @@ -6,16 +6,13 @@ spec_file: "09-security-and-development.md" order: 9 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/09-security-and-development.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/09-security-and-development.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/09-security-and-development.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/09-security-and-development.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/selection-aggregate.md b/src/content/docs/grading/selection-aggregate.md index 1e20ab7..d23d0f3 100644 --- a/src/content/docs/grading/selection-aggregate.md +++ b/src/content/docs/grading/selection-aggregate.md @@ -6,16 +6,13 @@ spec_file: "24-selection-aggregate.md" order: 24 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/24-selection-aggregate.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/24-selection-aggregate.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/24-selection-aggregate.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/24-selection-aggregate.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). diff --git a/src/content/docs/grading/selection-lockfile.md b/src/content/docs/grading/selection-lockfile.md index 31a1529..c10b2b5 100644 --- a/src/content/docs/grading/selection-lockfile.md +++ b/src/content/docs/grading/selection-lockfile.md @@ -6,16 +6,13 @@ spec_file: "16-selection-lockfile.md" order: 16 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/16-selection-lockfile.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/16-selection-lockfile.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/16-selection-lockfile.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/16-selection-lockfile.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/skills.md b/src/content/docs/grading/skills.md index a8284e1..2727447 100644 --- a/src/content/docs/grading/skills.md +++ b/src/content/docs/grading/skills.md @@ -6,16 +6,13 @@ spec_file: "13-skills.md" order: 13 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/13-skills.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/13-skills.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/13-skills.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/13-skills.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/tos.md b/src/content/docs/grading/tos.md index 548af87..29f27c8 100644 --- a/src/content/docs/grading/tos.md +++ b/src/content/docs/grading/tos.md @@ -6,16 +6,13 @@ spec_file: "03-tos.md" order: 3 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/03-tos.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/03-tos.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/03-tos.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/03-tos.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification. diff --git a/src/content/docs/grading/versioning-axes.md b/src/content/docs/grading/versioning-axes.md index f5c9ff4..f960378 100644 --- a/src/content/docs/grading/versioning-axes.md +++ b/src/content/docs/grading/versioning-axes.md @@ -6,16 +6,13 @@ spec_file: "15-versioning-axes.md" order: 15 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/15-versioning-axes.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/15-versioning-axes.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/15-versioning-axes.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/15-versioning-axes.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). The binding source is the FlowMCP Schemas Specification v4.3.0. diff --git a/src/content/docs/grading/workbench-island.md b/src/content/docs/grading/workbench-island.md index cc94926..afb8269 100644 --- a/src/content/docs/grading/workbench-island.md +++ b/src/content/docs/grading/workbench-island.md @@ -6,16 +6,13 @@ spec_file: "22-workbench-island.md" order: 22 section: "Grading" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/grading/3.0.0/22-workbench-island.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/grading/3.0.0/22-workbench-island.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "grading/3.0.0/22-workbench-island.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: grading/3.0.0/22-workbench-island.md." --- - > Conformance language (MUST/SHOULD/MAY) follows BCP 14 [RFC2119]/[RFC8174] as defined in [`00-overview.md`](/grading/overview/). diff --git a/src/content/docs/guides/agent-creation.mdx b/src/content/docs/guides/agent-creation.mdx deleted file mode 100644 index 9b58afc..0000000 --- a/src/content/docs/guides/agent-creation.mdx +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Agent Creation -description: Step-by-step guide for building a FlowMCP-driven AI agent — schema selection, skill definition, LLM loop. ---- -{/* PAGEFIND-META-START */} -Get Started -{/* PAGEFIND-META-END */} - -## Skill for ~/.claude/skills/ - -Drop this into `~/.claude/skills/flowmcp-agent-creation/SKILL.md`: - -```markdown ---- -name: flowmcp-agent-creation -description: Help a user build a FlowMCP-driven AI agent — schema selection, skill definition, LLM loop ---- - -# FlowMCP Agent Creation - -Use this skill when a user wants to build an AI agent that uses FlowMCP schemas as its tool layer. Guide them through schema selection, skill definition, and the LLM loop so they end up with a working multi-tool agent. - -## Steps - -1. Pick the data sources: `flowmcp search ` then `flowmcp call '{...}'` (e.g. one crypto + one mobility schema) — every tool in the configured `schemaFolders[]` is immediately callable, no activation step -2. List the available tools: `flowmcp list` -3. Define the agent skill in `~/.claude/skills//SKILL.md` — describe purpose, allowed tools, output shape -4. Wire the LLM loop: call FlowMCP with the user query, pass tool results back into the next turn -5. Test with a real prompt and verify the agent invokes the expected schemas -6. Reference the full tutorial: https://flowmcp.github.io/guides/agent-creation/ - -## References - -- Tutorial: https://flowmcp.github.io/guides/agent-creation/ -- FlowMCP CLI: https://github.com/FlowMCP/flowmcp-cli -``` - -This guide walks through building an AI agent that uses FlowMCP schemas as its tool layer. By the end, you have a working agent that pulls from multiple data sources and reasons across them with a single LLM loop. - -## What you build - -A simple "crypto research agent" that: - -- Pulls token prices from a CoinGecko schema -- Pulls on-chain data from an Etherscan schema -- Lets the LLM decide which tools to chain -- Returns a structured answer - -Total time: 15–20 minutes. - -## Prerequisites - -- Node.js 22+ -- FlowMCP CLI installed: `npm install -g github:FlowMCP/flowmcp-cli` -- An API key for one LLM (Anthropic, OpenAI, or local Ollama) - -## Step 1 — Discover two schemas - -```bash -flowmcp search coingecko -flowmcp search etherscan -flowmcp list -``` - -The tools from the configured `schemaFolders[]` are immediately available — `flowmcp list` shows them, and any tool missing an API key appears as `[disabled: missing KEY]`. - -## Step 2 — Define a Skill - -A Skill bundles a workflow with the right tools. Save this as `crypto-research-skill.mjs`: - -```javascript -export const skill = { - name: 'crypto-research', - inputs: { - token_name: 'string', - chain_id: 'number' - }, - prefill: { - currency: 'usd', - include_24h_change: true - }, - tools: [ - 'coingecko-tokens.simplePrice', - 'etherscan-tokens.tokenInfo' - ], - description: 'Look up a token by name, fetch price + chain info.' -} -``` - -The Skill carries its **own parameter reference**, prefilled defaults, and the curated tool list. The LLM does not have to guess. - -## Step 3 — Wire the LLM loop - -A minimal Node.js example using the Anthropic SDK: - -```javascript -import { Anthropic } from '@anthropic-ai/sdk' -import { skill } from './crypto-research-skill.mjs' - -const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }) - -const response = await client.messages.create({ - model: 'claude-haiku-4-5-20251001', - max_tokens: 1024, - tools: skill.tools.map( ( name ) => ({ name, input_schema: { type: 'object' } }) ), - messages: [{ - role: 'user', - content: 'Look up ETH price and contract info on Ethereum mainnet.' - }] -}) - -console.log( response.content ) -``` - -You should see the LLM pick `simplePrice` first, then `tokenInfo` — without you scripting the order. - -## Step 4 — Reach for a third schema - -When the user asks a different kind of question (e.g. "What is Aave's TVL?"), discover and call a third schema: - -```bash -flowmcp search defillama -flowmcp call defillama-tvl '{...}' -``` - -The agent now has three tools and can reason about which to call. - -## Production checklist - -- [ ] API keys live in `~/.flowmcp/.env`, never in the LLM context -- [ ] LLM-loop has a max-iteration cap (avoid runaway loops) -- [ ] Skill input validation rejects malformed input before LLM sees it -- [ ] Telemetry: log tool calls per agent session for debugging -- [ ] Mock mode tested for demos / offline scenarios - -## Next - -- [Concepts → Agents](/concepts/agents/) — the conceptual model -- [Specification → Agents](/specification/agents/) — full manifest schema -- [Reference → Programmatic API](/reference/core-methods/) — Node SDK reference diff --git a/src/content/docs/guides/gtfs-pilot.mdx b/src/content/docs/guides/gtfs-pilot.mdx deleted file mode 100644 index 368739b..0000000 --- a/src/content/docs/guides/gtfs-pilot.mdx +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: GTFS Pilot -description: Download a GTFS feed, convert it to SQLite with quality seal, and query it from FlowMCP — Berlin + Germany. ---- -{/* PAGEFIND-META-START */} -Ecosystem -{/* PAGEFIND-META-END */} - -## Skill for ~/.claude/skills/ - -Drop this into `~/.claude/skills/flowmcp-gtfs-pilot/SKILL.md`: - -```markdown ---- -name: flowmcp-gtfs-pilot -description: Help a user reproduce the FlowMCP v4.1 GTFS pilot — download a feed, build local SQLite, query from FlowMCP ---- - -# FlowMCP GTFS Pilot - -Use this skill when a user wants to set up local mobility databases (VBB Berlin, DELFI Germany) from a GTFS feed and query them through FlowMCP. Guide them from raw feed to running transit-routing queries. - -## Steps - -1. Pick the feed: VBB Berlin (~30 MB) for a small demo, DELFI (~245 MB) for nationwide coverage -2. Download the GTFS ZIP and unpack it into a working directory -3. Convert the GTFS files to SQLite with the quality-seal converter from the tutorial -4. Make the FlowMCP GTFS schema available to the CLI — its directory is listed in `schemaFolders[]` in `~/.flowmcp/config.json` (there is no activation step; configured schemas are directly callable) -5. Point the schema at the local SQLite via its required server param -6. Run a transit-routing query end-to-end (e.g. stops near a coordinate, departures within 30 min) -7. Reference the full tutorial: https://flowmcp.github.io/guides/gtfs-pilot/ - -## References - -- Tutorial: https://flowmcp.github.io/guides/gtfs-pilot/ -- FlowMCP CLI: https://github.com/FlowMCP/flowmcp-cli -``` - -This guide reproduces the FlowMCP v4.1 GTFS pilot. By the end, you have two queryable mobility databases (VBB Berlin, DELFI Germany) and can ask transit-routing questions in seconds. - -> 📖 Background: [Blog — FlowMCP v4.1 GTFS Add-on](/blog/) (Phase 3 pilot results). - -## What you set up - -- DELFI feed (Germany-wide, ~245 MB ZIP, CC-BY 4.0) -- VBB feed (Berlin / Brandenburg, ~83 MB ZIP, CC-BY 4.0) -- `geo-gtfs-toolkit` for conversion -- A FlowMCP schema (`sqlite-gtfs`) that auto-injects routing tools - -Total time: 20–30 minutes (mostly waiting for downloads + conversion). - -## Prerequisites - -- Node.js 22+ with `--max-old-space-size=8192` for the DELFI conversion (default 4 GB heap is too small) -- ~3 GB free disk space -- FlowMCP CLI installed -- `geo-gtfs-toolkit` cloned or installed from `github:FlowMCP/geo-gtfs-toolkit` - -## Step 0 — Install the FlowMCP CLI - -```bash -npm install -g github:FlowMCP/flowmcp-cli -flowmcp --version -flowmcp list -``` - -The CLI is needed to register the GTFS schema in Step 5. If you only want the SQLite files for direct queries, you can skip the CLI install — but the recommended hackathon flow uses it. - -## Step 1 — Download both feeds - -```bash -mkdir -p ~/.flowmcp/resources/gtfs -cd ~/.flowmcp/resources/gtfs - -# Germany-wide (~245 MB) -curl -L -o gtfs-delfi.zip https://download.gtfs.de/germany/free/latest.zip - -# Berlin / Brandenburg (~83 MB) -curl -L -o gtfs-vbb.zip https://www.vbb.de/vbbgtfs - -# Verify hashes for reproducibility -shasum -a 256 *.zip -``` - -The DELFI feed is regenerated daily — pin the hash + date if you need exact reproducibility. - -## Step 2 — Convert to SQLite - -```javascript -import { GtfsSqliteConverter } from 'geo-gtfs-toolkit' - -// VBB — passes validation, gets quality seal -const vbb = await GtfsSqliteConverter.start( { - input: '/Users/you/.flowmcp/resources/gtfs/gtfs-vbb.zip', - inputType: 'zip', - dbPath: '/Users/you/.flowmcp/resources/gtfs/gtfs-vbb.db', - sourceUrl: 'https://www.vbb.de/vbbgtfs' -} ) - -// DELFI — needs force mode (97k validation errors in pilot) -const delfi = await GtfsSqliteConverter.start( { - input: '/Users/you/.flowmcp/resources/gtfs/gtfs-delfi.zip', - inputType: 'zip', - dbPath: '/Users/you/.flowmcp/resources/gtfs/gtfs-delfi.db', - sourceUrl: 'https://download.gtfs.de/germany/free/latest.zip', - force: true -} ) - -console.log( 'VBB seal:', vbb.seal ) // 'sqlite-gtfs' -console.log( 'DELFI seal:', delfi.seal ) // null (no seal in force mode) -console.log( 'DELFI caps:', delfi.capabilities ) // routing: false → no findRoute injected -``` - -Run with `node --max-old-space-size=8192 convert.mjs`. - -## Step 3 — Query the database - -Direct SQLite: - -```bash -sqlite3 ~/.flowmcp/resources/gtfs/gtfs-vbb.db < st1.stop_sequence - ORDER BY dep LIMIT 5; -EOF -``` - -Or via FlowMCP (when the schema is active): - -```bash -flowmcp call gtfsvbb.findRoute '{"origin":"Berlin Hbf","destination":"Spandau"}' -``` - -## Step 4 — Read the capability matrix - -The DB has a `meta` table with the seal, capabilities, and validation report: - -```bash -sqlite3 ~/.flowmcp/resources/gtfs/gtfs-vbb.db \ - "SELECT key, substr(value, 1, 100) FROM meta;" -``` - -The FlowMCP-CLI reads `capabilities` and **only injects tools that the feed can answer**. DELFI without routing capability sees `searchStops` and `findStopsByGeo`, but not `findRoute` — no 404, no hallucination, the tool simply does not exist in the agent's tool set. - -## License attribution - -CC-BY 4.0 requires attribution in every response that uses the data: - -```json -{ - "data": { "route_id": "ICE793", "dep_time": "09:34" }, - "licenseAttribution": "Daten: DELFI e.V. / VBB GmbH, CC-BY 4.0", - "source": "gtfs-de | gtfs-vbb" -} -``` - -FlowMCP carries this in the output object — your downstream code must surface it to end users. - -## Next - -- [Blog — FlowMCP v4.1 GTFS Add-on](/blog/) — full pilot results, 5 use cases, performance -- [Specification → Resources](/specification/) — `source: 'sqlite-gtfs'` semantics -- [`geo-gtfs-toolkit` README](https://github.com/FlowMCP/geo-gtfs-toolkit) — converter API diff --git a/src/content/docs/guides/hackathon-kit.mdx b/src/content/docs/guides/hackathon-kit.mdx deleted file mode 100644 index bb3be91..0000000 --- a/src/content/docs/guides/hackathon-kit.mdx +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Hackathon Kit -description: 5-minute setup for hackathon teams — mock mode, ready-made tool sets, mobility + crypto demos. ---- -{/* PAGEFIND-META-START */} -Get Started -{/* PAGEFIND-META-END */} - -## Skill for ~/.claude/skills/ - -Drop this into `~/.claude/skills/flowmcp-hackathon-kit/SKILL.md`: - -```markdown ---- -name: flowmcp-hackathon-kit -description: Help a user complete the FlowMCP Hackathon Kit setup in under 30 minutes ---- - -# FlowMCP Hackathon Kit - -Use this skill when a user is preparing for a hackathon with FlowMCP. Walk them through the 5-minute setup, activating mock mode for offline demos, and pointing them at ready-made tool sets so they can prototype a multi-tool agent fast. - -## Steps - -1. Before installing, run a security check on the source. FlowMCP is not published to npm — it installs straight from GitHub (`github:FlowMCP/flowmcp-cli`). Review the repository and decide whether to proceed. -2. Install the CLI: `npm install -g github:FlowMCP/flowmcp-cli` -3. Run `flowmcp init` to create `~/.flowmcp/` -4. Verify with `flowmcp status` -5. For offline demos: activate mock mode per call with `--mock` -6. Discover a ready-made tool set (mobility or crypto) via `flowmcp search `, then call tools directly with `flowmcp call '{...}'` — no activation step -7. Reference the live tutorial for full context: https://flowmcp.github.io/guides/hackathon-kit/ - -## References - -- Tutorial: https://flowmcp.github.io/guides/hackathon-kit/ -- FlowMCP CLI: https://github.com/FlowMCP/flowmcp-cli -``` - -Hackathons are short. FlowMCP is built so a team can prototype a working multi-tool agent in under 30 minutes — without writing API integrations, without exposing keys, and without an internet connection in mock mode. - -## 5-minute setup - -```bash -# 1. Install the CLI -npm install -g github:FlowMCP/flowmcp-cli - -# 2. Run the initial setup (creates ~/.flowmcp/) -flowmcp init - -# 3. Verify -flowmcp status -``` - -That is enough to run mock-mode demos. For live data, add API keys to `~/.flowmcp/.env` per the schemas you activate. - -## Mock mode - -For demos at conference venues with flaky wifi, mock mode returns stable example responses without hitting the upstream APIs. Activate per-call: - -```bash -FLOWMCP_MOCK=1 flowmcp call coingecko-tokens.simplePrice '{"id":"bitcoin"}' -``` - -Every schema ships with a `tests` block that defines its mock response. Mock-mode means: the same input always returns the same output. Perfect for live demos. - -## Ready-made tool sets - -Three curated bundles cover the common hackathon themes. Every schema below is already available from the configured `schemaFolders[]` — discover it with `flowmcp search`, then call it directly with `flowmcp call`. No activation step. - -### Mobility (Berlin / Germany) - -```bash -flowmcp search gtfsvbb # Berlin / Brandenburg transit -flowmcp search gtfsde # Germany-wide schedules -flowmcp search overpass-osm # OpenStreetMap geo queries -flowmcp search dwd-weather # German weather forecasts -``` - -Pairs naturally with the [GTFS Pilot Guide](/guides/gtfs-pilot/). - -### Crypto / DeFi - -```bash -flowmcp search coingecko-tokens # Token prices, market data -flowmcp search etherscan-tokens # On-chain contract data -flowmcp search defillama-tvl # DeFi TVL -flowmcp search dexscreener # DEX pairs + boosts -``` - -### Government / Open Data - -```bash -flowmcp search arbeitsagentur # German job market -flowmcp search dpma # Patents / trademarks -flowmcp search bundesgesetzblatt # German federal law -flowmcp search dip # German parliament docs -``` - -## Live demo pattern - -Three principles that survive contact with audience questions: - -1. **API keys never in the LLM context.** They live in `~/.flowmcp/.env`. Show this to security-minded judges. -2. **Mock mode for demo, live mode for Q&A.** Have both ready. Toggle with `FLOWMCP_MOCK=1`. -3. **One tool per question first.** Resist the urge to chain four tools on stage. Chain in v2 after the audience understands what FlowMCP does. - -## Used at - -- DB InfraGO "Anschluss erreichen" Hackathon (Berlin Hbf, March 2026, Mobility Data challenge) - -If your team has used FlowMCP at an event, open a PR adding the line above. - -## Next - -- [Agent Creation Guide](/guides/agent-creation/) — how to build a multi-tool agent -- [GTFS Pilot Guide](/guides/gtfs-pilot/) — mobility-specific tooling -- [Schema Creation Guide](/guides/schema-creation/) — write your own schema for a missing API diff --git a/src/content/docs/introduction/use-cases.md b/src/content/docs/introduction/use-cases.md deleted file mode 100644 index 9bd2436..0000000 --- a/src/content/docs/introduction/use-cases.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Use Cases -description: Two scenarios that show FlowMCP + AI in action — how scattered data becomes one answer. ---- - -About - - -Two scenarios that show FlowMCP + AI in action — not how to build an agent, but how FlowMCP turns scattered data sources into one usable answer. Both cases assume an AI agent (Claude, GPT, or similar) connected to a research tool, planning software, or CLI workflow, with FlowMCP-CLI running as the data-access layer. - ---- - -## Use Case 1: Deep Research - -### Setup - -A research workflow — a custom pipeline, an internal dashboard, or a Notion / Obsidian workspace — has an AI agent attached. The agent's job is to pull together data from many sources to scope or answer a research question. FlowMCP-CLI runs alongside as the agent's tool for finding and calling normalized data sources. - -### The Prompt - -> We are planning an open-data project on air quality in German inner cities. Find data sources for fine-dust measurement stations, the open-data portals of Berlin, Munich, and Hamburg, weather stations for correlation, and give me a list with provider, license, sample endpoint, and update frequency. - -### What FlowMCP Does - -1. **Search the catalog** — The agent calls `flowmcp search` with tags like `airquality`, `opendata`, `berlin`, `weather`. FlowMCP returns matching schemas across many providers with provider name, license, and short description. -2. **Sample each schema** — For promising hits, the agent runs a sample call (`flowmcp call `). FlowMCP holds the API keys, signs the request, and returns the normalized response. The agent sees the data shape without seeing credentials. -3. **Combine and summarize** — The agent merges results from federal, city, and weather sources, deduplicates overlapping stations, and produces a table the user can act on. - -### Fixed Data Sources, One Answer - -The agent draws on a fixed set of curated data sources — federal, city, and weather feeds that were normalized once and are now reused on every request. Because those sources share a consistent shape and a single auth path, the agent merges them into one consolidated answer instead of reading a separate API documentation for each one. The work of understanding each source happens once, in the schema, and every agent benefits from it afterwards. - -> Instead of feeding the AI hundreds of tokens of API docs per request, it searches a normalized catalog. One schema investment, any number of agents. - -### Next steps - -- [CLI Setup →](/quickstart/quickstart/) — first call in under 5 minutes - ---- - -## Use Case 2: Mobility — Catching the Connection - -### Setup - -The GTFS pilot is real and documented (see [GTFS Pilot Guide](/guides/gtfs-pilot/)). FlowMCP v4.1 ships an add-on concept: external toolkits like `geo-gtfs-toolkit` extend the CLI with local SQLite databases for static schedules. The combination — static GTFS lookup plus live REST API for delays — is what makes this case work as a single CLI call instead of a juggling act between two agents. - -### The Prompt - -> I'm at Berlin Hbf, heading to Munich. My ICE at 8:05 is 12 minutes late. Do I still catch the connecting IC in Nuremberg at 12:33? If not, what's the next option? - -### What FlowMCP Does - -1. **GTFS-SQLite lookup** (via `geo-gtfs-toolkit` add-on, local DB) — Static schedule for ICE 8:05 → connecting IC 12:33, scheduled transfer time 9 min, platform layout in Nuremberg. -2. **Live delay query** (Deutsche Bahn REST API via FlowMCP schema) — Current arrival forecast in Nuremberg 12:29 (was 12:17), so transfer time is now 4 min — critical. -3. **Alternative search** (GTFS-SQLite + REST combined) — Next IC 13:33 as fallback, arriving Munich 14:55. -4. **AI answer** — "IC 12:33 with only 4 min transfer is not reliable. Backup: IC 13:33, arriving Munich 14:55 instead of 13:13." - -**Local SQLite for static lookup + Live API through FlowMCP — one CLI call, one answer.** Without FlowMCP, the agent would have to orchestrate the static GTFS query and the live REST API separately, parse different formats, and merge them by hand. - -### Next steps - -- [GTFS Pilot Guide →](/guides/gtfs-pilot/) — the full mobility add-on story -- [CLI Setup →](/quickstart/quickstart/) — first call in under 5 minutes diff --git a/src/content/docs/quickstart/quickstart.mdx b/src/content/docs/quickstart/quickstart.mdx index 889ae47..9045566 100644 --- a/src/content/docs/quickstart/quickstart.mdx +++ b/src/content/docs/quickstart/quickstart.mdx @@ -6,18 +6,12 @@ description: "Create your first FlowMCP schema and call an API in 5 minutes" Get Started {/* PAGEFIND-META-END */} -import { Aside } from '@astrojs/starlight/components' import InstallNote from '../../../components/InstallNote.astro' import refs from '../../../data/refs.json' export const schemaCount = refs?.stats?.count_schemas ?? '—' export const toolCount = refs?.stats?.count_tools ?? '—' - - ## Install the CLI The FlowMCP CLI is the fastest path to a working setup. It lets you search the {toolCount}-tool catalog, add schemas, and call APIs without writing code. @@ -48,7 +42,7 @@ Two commands and you have a live API call — there is no activation step. The C - **npm** — comes with Node.js :::note[Embedding FlowMCP in your own code?] -The CLI is the fastest path for setup, hackathons, and exploring the catalog. If you want to embed FlowMCP directly in a Node.js application — load schemas, validate them, and call APIs programmatically — use the core library instead. The full method reference, including running your schema as an MCP server, lives on the [Programmatic API](/reference/core-methods/) page. +The CLI is the fastest path for setup, hackathons, and exploring the catalog. If you want to embed FlowMCP directly in a Node.js application — load schemas, validate them, and call APIs programmatically — use the core library instead. ::: ## What's Next @@ -61,10 +55,6 @@ Write your own schema for an API not in the catalog. See [Schema Creation](/guid Learn the full schema format with authentication, parameters, and handlers. See [Schema Creation](/guides/schema-creation/). ::: -:::note[CLI Reference] -Search, list, and call {schemaCount} pre-built schemas from the command line. See [CLI Usage](/reference/cli/). -::: - :::note[Examples] Real-world schema examples for common APIs. See [Examples](/guides/examples/). ::: diff --git a/src/content/docs/quickstart/what-is-flowmcp.mdx b/src/content/docs/quickstart/what-is-flowmcp.mdx index 882a747..f1f34f8 100644 --- a/src/content/docs/quickstart/what-is-flowmcp.mdx +++ b/src/content/docs/quickstart/what-is-flowmcp.mdx @@ -119,7 +119,7 @@ System requirements and setup instructions. See [Installation](/quickstart/insta ::: :::note[CLI Reference] -Complete command reference for search, list, call, validate, and grading. See [CLI Usage](/reference/cli/). +Complete command reference for search, list, call, validate, and grading. See [Quickstart](/quickstart/quickstart/). ::: :::note[Schema Creation] diff --git a/src/content/docs/reference/cli.mdx b/src/content/docs/reference/cli.mdx deleted file mode 100644 index 4bd808b..0000000 --- a/src/content/docs/reference/cli.mdx +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: CLI Usage -description: Search, list, and call FlowMCP tools from the command line ---- -{/* PAGEFIND-META-START */} -Reference -{/* PAGEFIND-META-END */} - -import InstallNote from '../../../components/InstallNote.astro'; - -:::note[New to FlowMCP?] -This page is the complete CLI reference. For a guided five-minute install and your first live API call, start with [CLI Setup](/quickstart/quickstart/). -::: - -## Installation - - - -## CLI Workflow - -The CLI follows a two-step pattern: discover tools, then call them. There is no activation step — every tool in the configured `schemaFolders[]` is immediately callable. - -```mermaid -flowchart TD - A[flowmcp search query] --> B[Browse matching tools + parameters] - B --> E[flowmcp call tool-name JSON-args] - E --> F[Tool result returned] -``` - -## Core Commands - -| Command | Description | -|---------|-------------| -| `flowmcp search ` | Find tools (max 10 results), showing required parameters | -| `flowmcp list` | Show all available tools (with `disabledCount`) | -| `flowmcp call '{json}'` | Call a tool with JSON parameters | -| `flowmcp status` | Health check | - -## Search, List, Call - -Discover tools by keyword — the response shows each tool's required parameters. Then call the tool directly with JSON arguments. There is no activation step: every tool from the configured `schemaFolders[]` is immediately callable. A tool that is missing an API key shows up as `[disabled: missing KEY]`. - -```bash -flowmcp search ethereum -flowmcp call get_contract_abi_etherscan '{"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"}' -``` - -`flowmcp list` shows the full catalog, including how many tools are disabled because of missing keys. - -:::note[Programmatic Usage] -For programmatic access (not via CLI), see the [Programmatic API](/reference/core-methods). -::: - -## Agent Mode vs Dev Mode - -The CLI has two operating modes that control which commands are available: - -| Mode | Commands | Use Case | -|------|----------|----------| -| **Agent** | search, list, call, status | Daily AI agent usage | -| **Dev** | + validate, grading, migrate | Schema development | - -```bash -flowmcp mode dev # Switch to dev mode -flowmcp mode agent # Switch back to agent mode -``` - -:::note[Default Mode] -Agent mode is the default. It exposes only the commands an AI agent needs to discover and call tools. Switch to Dev mode for schema development and validation workflows. -::: - -## Dev Mode Commands - -Dev mode unlocks additional commands for schema authors: - -```bash -flowmcp validate # Validate schema structure -flowmcp grading deterministic # Structural validate + live data pretest (alias: det) -flowmcp grading non-deterministic # LLM scoring (alias: nondet) -flowmcp validate-agent # Validate agent manifest -``` - -## Local Project Config - -The CLI reads its configured `schemaFolders[]` from a `.flowmcp/` directory in your project: - -``` -.flowmcp/ -└── config.json # Configured schemaFolders[] + mode -``` - -`config.json` lists the schema folders the CLI loads. Every tool in those folders is immediately available to `search`, `list`, and `call` — no per-tool activation file is written. - -## API Keys - -:::tip[API Key Management] -Some tools require API keys stored in `~/.flowmcp/.env`. If a `call` fails because of missing keys, add the required key to your global config: - -```bash -echo "ETHERSCAN_API_KEY=your_key_here" >> ~/.flowmcp/.env -``` - -Never commit API keys to version control. The `.env` file in `~/.flowmcp/` is your global key store and should stay on your machine only. -::: - -## Grading (Experimental) - -:::caution[Experimental] -The `grading` command area is **experimental** — its CLI surface may change. It drives the FlowMCP [Grading standard](/grading/overview/) (`gradingSpec`), which scores and grades schemas and selections. -::: - -The CLI stores its grading working data — the **workbench island** — next to your global config, **not** in any repository. Default location and override chain: - -| Priority | Source | Example | -|----------|--------|---------| -| 1 | `--grading-data ` flag | per-call override | -| 2 | `FLOWMCP_GRADING_DATA` env var | shell/session override | -| 3 | `gradingDataDir` in `~/.flowmcp/config.json` | persistent config | -| 4 | Default | `~/.flowmcp/grading/` | - -This island holds runtime grading data only. It lives in your home directory, is never published, and must not be committed. The published **Grading standard** itself is the versioned spec at [`/grading/`](/grading/overview/). diff --git a/src/content/docs/reference/core-methods.md b/src/content/docs/reference/core-methods.md deleted file mode 100644 index cfa4ab7..0000000 --- a/src/content/docs/reference/core-methods.md +++ /dev/null @@ -1,637 +0,0 @@ ---- -title: Core API Methods -description: Complete FlowMCP Core method reference ---- - -Reference - - -Complete reference for all public methods in `flowmcp-core`. Methods are organized by usage category. All methods are static. - -```javascript -import { FlowMCP } from 'flowmcp-core' -``` - -:::note -FlowMCP Core exports both v3 (default) and legacy APIs. This reference covers the current v3 API. For v1 methods, import from `flowmcp-core/v1`. -::: - -## Method Overview - -| Method | Purpose | Returns | -|--------|---------|---------| -| `.loadSchema()` | Load and validate a schema file | `{ status, main, handlerMap }` | -| `.validateMain()` | Validate a main export against validation rules | `{ status, messages }` | -| `.scanSecurity()` | Run security scan on a schema file | `{ status, messages }` | -| `.fetch()` | Execute an API request for a tool | `{ status, dataAsString, messages }` | -| `.resolveSharedLists()` | Resolve shared list references | `{ sharedLists }` | -| `.interpolateEnum()` | Interpolate shared list values into enum templates | `{ result }` | -| `.loadLibraries()` | Load declared libraries from allowlist | `{ libraries }` | -| `.createHandlers()` | Create handler map from factory function | `{ handlerMap }` | -| `.detectLegacy()` | Detect if a module uses v1 format | `{ isLegacy, format }` | -| `.adaptLegacy()` | Convert a v1 schema to v2 format | `{ main, handlersFn, hasHandlers, warnings }` | -| `.getDefaultAllowlist()` | Get the default library allowlist | `{ allowlist }` | -| `.generateOutputSchema()` | Generate output schema from API response | `{ output }` | - ---- - -## Schema Loading & Validation - -### .loadSchema() - -Loads a `.mjs` schema file, runs security scanning, validates the `main` export, resolves shared lists, loads declared libraries, creates the handler map, and processes any resources and skills. This is the primary entry point for working with schemas. - -**Method** -```javascript -const result = await FlowMCP.loadSchema( { filePath, listsDir, allowlist } ) -``` - -**Parameters** - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `filePath` | string | Absolute or relative path to the `.mjs` schema file | Yes | -| `listsDir` | string | Directory containing shared list files | No | -| `allowlist` | array | Allowed library names for handlers. Uses default if omitted | No | - -**Example** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { status, main, handlerMap } = await FlowMCP.loadSchema( { - filePath: './schemas/coingecko-price.mjs' -} ) - -if( !status ) { - console.error( 'Schema loading failed' ) -} - -// Use the loaded schema -const result = await FlowMCP.fetch( { - main, - handlerMap, - userParams: { id: 'bitcoin' }, - serverParams: {}, - routeName: 'getPrice' -} ) -``` - -**Returns** -```javascript -{ - status: true, // false if loading, validation, or security scan failed - main: { ... }, // The validated main export object (with tools, resources, skills) - handlerMap: { ... } // Tool-keyed handler functions (empty object if no handlers) -} -``` - -### .validateMain() - -Validates a `main` export object against the FlowMCP specification. Runs validation rules across categories including structure, naming, parameters, security, output declarations, resources, and skills. - -**Method** -```javascript -const { status, messages } = FlowMCP.validateMain( { main } ) -``` - -**Parameters** - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `main` | object | The `main` export from a schema file. Accepts both `tools` and `routes` (deprecated alias) | Yes | - -**Example** -```javascript -import { FlowMCP } from 'flowmcp-core' -import { main } from './schemas/coingecko-price.mjs' - -const { status, messages } = FlowMCP.validateMain( { main } ) - -if( status ) { - console.log( 'Schema is valid' ) -} else { - console.error( 'Validation failed:' ) - messages.forEach( ( msg ) => console.error( ` - ${msg}` ) ) -} -``` - -**Returns** -```javascript -{ - status: true, // true if all rules pass - messages: [] // Array of error messages when status is false -} -``` - -:::tip -Use `validateMain()` during development to catch schema errors early. In production, use `loadSchema()` which includes validation as part of the full pipeline. -::: - -### .scanSecurity() - -Runs a static security scan on a schema file. Checks for forbidden patterns like `import` statements, `require()` calls, filesystem access, `eval()`, and other disallowed constructs. - -**Method** -```javascript -const { status, messages } = await FlowMCP.scanSecurity( { filePath } ) -``` - -**Parameters** - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `filePath` | string | Path to the `.mjs` schema file to scan | Yes | - -**Example** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { status, messages } = await FlowMCP.scanSecurity( { - filePath: './schemas/my-schema.mjs' -} ) - -if( !status ) { - console.error( 'Security violations found:' ) - messages.forEach( ( msg ) => console.error( ` - ${msg}` ) ) -} -``` - -**Returns** -```javascript -{ - status: true, // false if forbidden patterns are detected - messages: [] // Descriptions of security violations -} -``` - ---- - -## Execution - -### .fetch() - -Executes an HTTP request for a specific tool using the loaded schema. Handles parameter substitution, URL construction, header injection, and optional pre/post-processing via handlers. - -**Method** -```javascript -const result = await FlowMCP.fetch( { main, handlerMap, userParams, serverParams, routeName } ) -``` - -**Parameters** - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `main` | object | The validated `main` export from a schema | Yes | -| `handlerMap` | object | Handler map from `loadSchema()` or `createHandlers()` | Yes | -| `userParams` | object | User-provided parameters (from AI client input) | Yes | -| `serverParams` | object | Server-side parameters (API keys, tokens) | Yes | -| `routeName` | string | Name of the tool to execute | Yes | - -**Example** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { status, main, handlerMap } = await FlowMCP.loadSchema( { - filePath: './schemas/coingecko-price.mjs' -} ) - -const result = await FlowMCP.fetch( { - main, - handlerMap, - userParams: { id: 'bitcoin', vs_currency: 'usd' }, - serverParams: {}, - routeName: 'getPrice' -} ) - -if( result.status ) { - console.log( 'Response:', result.dataAsString ) -} else { - console.error( 'Request failed:', result.messages ) -} -``` - -**Returns** -```javascript -{ - status: true, // false if request failed - dataAsString: '{"bitcoin":{"usd":45000}}', // Response body as string - messages: [] // Error messages when status is false -} -``` - -:::caution -The `serverParams` object should contain API keys and secrets. These values are injected into headers and parameters at runtime but are never exposed to AI clients. -::: - ---- - -## Shared Lists & Dependencies - -### .resolveSharedLists() - -Resolves shared list references from a directory of list files. Shared lists are reusable value collections (chain IDs, token symbols, protocol names) that schemas reference via `$listName` syntax in enum parameters. - -**Method** -```javascript -const { sharedLists } = await FlowMCP.resolveSharedLists( { sharedListRefs, listsDir } ) -``` - -**Parameters** - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `sharedListRefs` | array | Array of shared list reference strings from the schema | Yes | -| `listsDir` | string | Directory path containing shared list `.mjs` files | Yes | - -**Example** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { sharedLists } = await FlowMCP.resolveSharedLists( { - sharedListRefs: [ 'evmChains', 'stablecoins' ], - listsDir: './lists/' -} ) - -console.log( 'Resolved lists:', Object.keys( sharedLists ) ) -// Output: ['evmChains', 'stablecoins'] -``` - -**Returns** -```javascript -{ - sharedLists: { - evmChains: [ 'ethereum', 'polygon', 'arbitrum', ... ], - stablecoins: [ 'USDT', 'USDC', 'DAI', ... ] - } -} -``` - -### .interpolateEnum() - -Interpolates shared list values into an enum template string. Replaces `$listName` references with actual values from resolved shared lists. - -**Method** -```javascript -const { result } = FlowMCP.interpolateEnum( { template, sharedLists } ) -``` - -**Parameters** - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `template` | string | Enum template containing `$listName` references | Yes | -| `sharedLists` | object | Resolved shared lists from `resolveSharedLists()` | Yes | - -**Example** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const sharedLists = { - evmChains: [ 'ethereum', 'polygon', 'arbitrum' ] -} - -const { result } = FlowMCP.interpolateEnum( { - template: '$evmChains', - sharedLists -} ) - -console.log( result ) -// Output: ['ethereum', 'polygon', 'arbitrum'] -``` - -**Returns** -```javascript -{ - result: [ 'ethereum', 'polygon', 'arbitrum' ] // Resolved enum values -} -``` - -### .loadLibraries() - -Loads npm packages declared in a schema's `requiredLibraries` field. Only packages on the allowlist can be loaded. This enforces the zero-import security model. - -**Method** -```javascript -const { libraries } = await FlowMCP.loadLibraries( { requiredLibraries, allowlist } ) -``` - -**Parameters** - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `requiredLibraries` | array | Library names declared in the schema | Yes | -| `allowlist` | array | Permitted library names. Use `getDefaultAllowlist()` for defaults | Yes | - -**Example** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { allowlist } = FlowMCP.getDefaultAllowlist() - -const { libraries } = await FlowMCP.loadLibraries( { - requiredLibraries: [ 'ethers' ], - allowlist -} ) - -// libraries.ethers is now available for handler injection -``` - -**Returns** -```javascript -{ - libraries: { - ethers: { ... } // The loaded library module - } -} -``` - -### .getDefaultAllowlist() - -Returns the default library allowlist. These are the npm packages that handlers are permitted to use via dependency injection. - -**Method** -```javascript -const { allowlist } = FlowMCP.getDefaultAllowlist() -``` - -**Parameters** - -None. - -**Example** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { allowlist } = FlowMCP.getDefaultAllowlist() -console.log( 'Allowed libraries:', allowlist ) -``` - -**Returns** -```javascript -{ - allowlist: [ 'ethers', 'viem', ... ] // Array of permitted library names -} -``` - ---- - -## Handler Management - -### .createHandlers() - -Creates a handler map by invoking the `handlers` factory function with injected dependencies. The resulting map is keyed by tool name and contains `preProcess` and `postProcess` functions. - -**Method** -```javascript -const { handlerMap } = FlowMCP.createHandlers( { handlersFn, sharedLists, libraries, routeNames } ) -``` - -**Parameters** - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `handlersFn` | function | The `handlers` factory function from a schema | Yes | -| `sharedLists` | object | Resolved shared lists to inject | Yes | -| `libraries` | object | Loaded libraries to inject | Yes | -| `routeNames` | array | Expected tool names for validation | Yes | - -**Example** -```javascript -import { FlowMCP } from 'flowmcp-core' -import { handlers } from './schemas/my-schema.mjs' - -const { handlerMap } = FlowMCP.createHandlers( { - handlersFn: handlers, - sharedLists: { evmChains: [ 'ethereum', 'polygon' ] }, - libraries: {}, - routeNames: [ 'getPrice', 'getHistory' ] -} ) - -// handlerMap.getPrice.postProcess is now available -``` - -**Returns** -```javascript -{ - handlerMap: { - getPrice: { - postProcess: async ( { data } ) => { ... } - }, - getHistory: { - preProcess: async ( { params } ) => { ... }, - postProcess: async ( { data } ) => { ... } - } - } -} -``` - -:::tip -You rarely need to call `createHandlers()` directly. The `loadSchema()` pipeline handles handler creation automatically. Use this method when you need manual control over the dependency injection process. -::: - ---- - -## Legacy Compatibility - -### .detectLegacy() - -Detects whether a loaded module uses the v1 schema format. Returns the detected format version. - -**Method** -```javascript -const { isLegacy, format } = FlowMCP.detectLegacy( { module } ) -``` - -**Parameters** - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `module` | object | The imported module from a `.mjs` schema file | Yes | - -**Example** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const schemaModule = await import( './schemas/old-schema.mjs' ) -const { isLegacy, format } = FlowMCP.detectLegacy( { module: schemaModule } ) - -if( isLegacy ) { - console.log( `Legacy format detected: ${format}` ) - // Use adaptLegacy() to convert -} -``` - -**Returns** -```javascript -{ - isLegacy: true, // true if the module uses v1 format - format: 'v1' // Detected format version string -} -``` - -### .adaptLegacy() - -Converts a v1 schema object to the v2 two-export format. Returns the adapted `main` export, optional handlers factory function, and any conversion warnings. - -**Method** -```javascript -const { main, handlersFn, hasHandlers, warnings } = FlowMCP.adaptLegacy( { legacySchema } ) -``` - -**Parameters** - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `legacySchema` | object | A v1 format schema object | Yes | - -**Example** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const oldSchema = { namespace: 'myapi', root: '...', routes: { ... } } -const { main, handlersFn, hasHandlers, warnings } = FlowMCP.adaptLegacy( { - legacySchema: oldSchema -} ) - -if( warnings.length > 0 ) { - console.log( 'Migration warnings:' ) - warnings.forEach( ( w ) => console.log( ` - ${w}` ) ) -} - -// Use the adapted schema with current methods -const result = await FlowMCP.fetch( { - main, - handlerMap: {}, - userParams: { ... }, - serverParams: {}, - routeName: 'myRoute' -} ) -``` - -**Returns** -```javascript -{ - main: { ... }, // Converted main export - handlersFn: Function|null, // Handlers factory (null if no handlers) - hasHandlers: false, // Whether the schema had handlers - warnings: [] // Conversion warnings (deprecated features, etc.) -} -``` - ---- - -## Output Schema Generation - -### .generateOutputSchema() - -Generates an output schema from a captured API response. The output schema declares the expected response shape for downstream consumers and documentation. - -**Method** -```javascript -const { output } = FlowMCP.generateOutputSchema( { response, mimeType } ) -``` - -**Parameters** - -| Key | Type | Description | Required | -|-----|------|-------------|----------| -| `response` | string | Raw API response body | Yes | -| `mimeType` | string | Response MIME type (e.g. `application/json`) | Yes | - -**Example** -```javascript -import { FlowMCP } from 'flowmcp-core' - -const { output } = FlowMCP.generateOutputSchema( { - response: '{"bitcoin":{"usd":45000,"eur":38000}}', - mimeType: 'application/json' -} ) - -console.log( output ) -// { type: 'object', fields: { bitcoin: { type: 'object', fields: { ... } } } } -``` - -**Returns** -```javascript -{ - output: { - type: 'object', - fields: { ... } // Inferred field structure from the response - } -} -``` - -:::tip -Use this method during schema development to auto-generate the `output` block for your tools. Capture a real API response with `fetch()`, then pass it to `generateOutputSchema()`. -::: - ---- - -## v1 API (Legacy) - -The v1 API is still available for backward compatibility. Import it separately: - -```javascript -import { v1 } from 'flowmcp-core' -const { FlowMCP } = v1 -``` - -
-v1 Method Overview - -The v1 API uses a flat schema format (single export) with different method signatures. - -| Method | v1 Signature | Current Equivalent | -|--------|-------------|---------------| -| `.validateSchema()` | `FlowMCP.validateSchema( { schema } )` | `.validateMain( { main } )` | -| `.fetch()` | `FlowMCP.fetch( { schema, userParams, serverParams, routeName } )` | `.fetch( { main, handlerMap, ... } )` | -| `.activateServerTools()` | `FlowMCP.activateServerTools( { server, schema, serverParams } )` | Use MCP SDK directly with `.loadSchema()` | -| `.activateServerTool()` | `FlowMCP.activateServerTool( { server, schema, routeName, serverParams } )` | Use MCP SDK directly | -| `.prepareServerTool()` | `FlowMCP.prepareServerTool( { schema, serverParams, routeName } )` | Use `.loadSchema()` + `.fetch()` | -| `.filterArrayOfSchemas()` | `FlowMCP.filterArrayOfSchemas( { arrayOfSchemas, ... } )` | Same (v1 only) | -| `.getArgvParameters()` | `FlowMCP.getArgvParameters( { argv } )` | Same (v1 only) | -| `.getZodInterfaces()` | `FlowMCP.getZodInterfaces( { schema } )` | Zod schemas are generated during `.loadSchema()` | -| `.getAllTests()` | `FlowMCP.getAllTests( { schema } )` | Test values are in parameter `test` fields | - -:::caution -The v1 API will be maintained for backward compatibility but will not receive new features. All new schemas should use the v3 format. -::: - -
- ---- - -## Typical Workflow - -The standard workflow for using FlowMCP Core combines these methods: - -```javascript -import { FlowMCP } from 'flowmcp-core' - -// 1. Load schema (validates, scans security, resolves lists, creates handlers) -const { status, main, handlerMap } = await FlowMCP.loadSchema( { - filePath: './schemas/coingecko-price.mjs' -} ) - -if( !status ) { - throw new Error( 'Schema loading failed' ) -} - -// 2. Execute a tool -const result = await FlowMCP.fetch( { - main, - handlerMap, - userParams: { id: 'bitcoin' }, - serverParams: { API_KEY: process.env.COINGECKO_KEY }, - routeName: 'getPrice' -} ) - -// 3. Use the result -if( result.status ) { - console.log( 'Price data:', result.dataAsString ) -} else { - console.error( 'Errors:', result.messages ) -} -``` - -For MCP server integration, see the [Server Integration Guide](/guides/server-integration). diff --git a/src/content/docs/reference/mcp-server.md b/src/content/docs/reference/mcp-server.md deleted file mode 100644 index face6dc..0000000 --- a/src/content/docs/reference/mcp-server.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: MCP Server -description: Run FlowMCP as an MCP server to integrate with Claude Desktop, Cursor, and other AI tools ---- - -Reference - - - -## What is MCP? - -The **Model Context Protocol (MCP)** is an open standard for connecting AI models to external tools and data sources. FlowMCP can run as an MCP server, exposing all active schemas as tools to any MCP-compatible AI client. - -Instead of writing custom server code for each API, you declare schemas and FlowMCP handles the MCP protocol, parameter validation, and API execution. - -## Architecture - -How FlowMCP bridges AI clients and APIs: - -The AI client sends tool calls over the MCP protocol. FlowMCP resolves the correct schema, validates parameters, calls the upstream API, and returns the result. - -## Starting the Server - -The fastest way to serve schemas is through the CLI: - -```bash -# Serve all active tools as MCP server (stdio) -flowmcp run - -# Serve a specific group -flowmcp run --group crypto -``` - -For programmatic control, see the [Server Integration guide](/guides/server-integration). - -## Client Integration - -### Claude Desktop - -Add FlowMCP to your `claude_desktop_config.json`: - -```json -{ - "mcpServers": { - "flowmcp": { - "command": "npx", - "args": ["-y", "flowmcp", "run"], - "env": { - "ETHERSCAN_API_KEY": "your_key_here", - "MORALIS_API_KEY": "your_key_here" - } - } - } -} -``` - -Config file location: -- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - -:::tip -After editing the config, restart Claude Desktop to pick up the new MCP server configuration. -::: - -### Cursor - -Add FlowMCP to your Cursor MCP settings: - -```json -{ - "mcpServers": { - "flowmcp": { - "command": "npx", - "args": ["-y", "flowmcp", "run"] - } - } -} -``` - -Open Cursor Settings and navigate to the MCP section to add this configuration. - -### Claude Code - -Add FlowMCP as a local MCP server: - -```bash -claude mcp add flowmcp --scope local -- npx -y flowmcp run -``` - -Claude Code will automatically start the server when needed. - -## Environment Variables - -API keys required by your schemas can be provided in three ways: - -| Method | Example | Best For | -|--------|---------|----------| -| `~/.flowmcp/.env` file | `ETHERSCAN_API_KEY=abc123` | Persistent local setup | -| `env` block in client config | See Claude Desktop example above | Per-client configuration | -| System environment variables | `export ETHERSCAN_API_KEY=abc123` | CI/CD and containers | - -:::note[Security] -API keys are injected as server parameters at runtime and are never exposed to the AI client. They are only used when FlowMCP calls the upstream API on behalf of the AI. -::: - -## What Gets Exposed - -All active tools from your `.flowmcp/config.json` become MCP primitives: - -| Schema Primitive | MCP Primitive | Description | -|-----------------|---------------|-------------| -| Tools | MCP Tools | API endpoints the AI can call | -| Resources | MCP Resources | Static data the AI can read | -| Prompts | MCP Prompts | Pre-built prompt templates | - -Each tool is registered with its name, description, and a Zod-validated parameter schema -- giving the AI client everything it needs to discover and call the tool correctly. - -## What's Next - -:::note[Server Integration] -For programmatic server setup with stdio and HTTP/SSE transports, see the [Server Integration guide](/guides/server-integration). -::: diff --git a/src/content/docs/schemas-and-sources.md b/src/content/docs/schemas-and-sources.md deleted file mode 100644 index e90ee0e..0000000 --- a/src/content/docs/schemas-and-sources.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Schemas & Sources -description: The three layers of FlowMCP — engine, schemas, and data operators — and why FlowMCP neither publishes nor displays schemas. ---- - -FlowMCP is built from three layers that are easy to confuse but stay strictly separate. Keeping them apart is the key to understanding what FlowMCP is responsible for and what it is not. - -## Engine, Schemas, and Data Operators - -The **engine** is the part FlowMCP builds and maintains. It is the Core library and the CLI that load a schema, sign the request, call the source, and normalize the response. The engine is MIT-licensed, open source, and the same audit covers every call that flows through it. - -A **schema** is a thin declaration that tells the engine how to reach one data source and how to shape its response. Schemas are community contributions: anyone can write one for an API or dataset. They are not part of the engine, and a schema can be added, replaced, or removed without touching the engine at all. - -A **data operator** is whoever runs the API or publishes the dataset behind a schema. They decide their own Terms of Service, data license, and rate limits. FlowMCP has no control over that layer — it only passes the call through and returns the answer. - -These three layers never merge. The engine moves data, schemas describe sources, and operators own the data. Confusing them is the most common source of misunderstanding about what FlowMCP does. - -## What FlowMCP Does Not Do - -FlowMCP **does not publish schemas, and it does not show schemas on this website.** There is no catalog page, no schema browser, and no hosted list of sources here. Schemas live in their own repositories and are loaded by the CLI on demand; the website explains the engine and the model, not the individual schemas. - -Because the data operators own the source and its terms, FlowMCP also makes no judgment about them. We record a few neutral facts where a provider publishes them — the Terms of Service URL (`meta.termsOfService`), the date we last checked it (`meta.termsOfServiceCheckedAt`), and the data license name when one is stated (`meta.dataLicenseName`) — and we link out to the original. We do not classify those terms, interpret them, or advise on commercial use. Reviewing a provider's Terms of Service, rate limits, and data license before you rely on a source remains your responsibility, and FlowMCP makes no warranty about fitness for any purpose. - -## See Also - -- [Specification: License & ToS (spec/v4.3.0/23-license-and-tos.md)](https://github.com/FlowMCP/flowmcp-spec/blob/main/spec/v4.3.0/23-license-and-tos.md) -- [DISCLAIMER.md in flowmcp-core](https://github.com/FlowMCP/flowmcp-core/blob/main/DISCLAIMER.md) -- [DISCLAIMER.md in flowmcp-cli](https://github.com/FlowMCP/flowmcp-cli/blob/main/DISCLAIMER.md) diff --git a/src/content/docs/specification/agents.md b/src/content/docs/specification/agents.md index 61eed8a..f64f59f 100644 --- a/src/content/docs/specification/agents.md +++ b/src/content/docs/specification/agents.md @@ -6,16 +6,13 @@ spec_file: "06-agents.md" order: 6 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/06-agents.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/06-agents.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/06-agents.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/06-agents.md." --- - An Agent is a complete, purpose-driven definition that bundles tools from multiple providers for a specific task. Unlike a plain tool list, an Agent is a full composition: it cherry-picks tools across providers, binds them to a specific LLM, defines a system prompt and behavioral guidelines, and ships with its own tests, explanatory prompts, instructional skills, and optional resources. The sections below cover the agent manifest format, how tool references are resolved, model binding, the system prompt, integrity verification through hashes, and the validation rules applied at activation. diff --git a/src/content/docs/specification/catalog.md b/src/content/docs/specification/catalog.md index 1b92a25..d2f24f9 100644 --- a/src/content/docs/specification/catalog.md +++ b/src/content/docs/specification/catalog.md @@ -6,16 +6,13 @@ spec_file: "15-catalog.md" order: 15 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/15-catalog.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/15-catalog.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/15-catalog.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/15-catalog.md." --- - A Catalog is the top-level organizational unit in FlowMCP v3. It is a named directory containing a `registry.json` manifest that describes all shared lists, provider schemas, and agent definitions within that directory. Multiple catalogs can coexist side by side, enabling community, company-internal, and experimental tool collections to operate independently. diff --git a/src/content/docs/specification/id-schema.md b/src/content/docs/specification/id-schema.md index 71462d0..bb5228b 100644 --- a/src/content/docs/specification/id-schema.md +++ b/src/content/docs/specification/id-schema.md @@ -6,16 +6,13 @@ spec_file: "16-id-schema.md" order: 16 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/16-id-schema.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/16-id-schema.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/16-id-schema.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/16-id-schema.md." --- - A FlowMCP catalog exposes three MCP primitives — Tools, Resources, and Skills (prompts) — across potentially hundreds of schemas from dozens of providers, and references to those primitives turn up everywhere: group definitions, skill placeholders, registry entries, CLI commands, and cross-schema dependencies. Without a unified scheme, a bare name like `lookupItem` is ambiguous — is it a tool, a resource, or a prompt, and which provider owns it? The ID schema removes that ambiguity by giving every tool, resource, prompt, and shared list exactly one canonical, human-readable, resolvable identifier built from a namespace, a type discriminator, and a name. diff --git a/src/content/docs/specification/license-and-tos.md b/src/content/docs/specification/license-and-tos.md index 26c0b4c..01ba5c8 100644 --- a/src/content/docs/specification/license-and-tos.md +++ b/src/content/docs/specification/license-and-tos.md @@ -6,16 +6,13 @@ spec_file: "23-license-and-tos.md" order: 23 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/23-license-and-tos.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/23-license-and-tos.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/23-license-and-tos.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/23-license-and-tos.md." --- - FlowMCP sits between its own code, the third-party APIs a schema calls, and the data those APIs return — and each of those carries its own legal terms. The purpose of this page is to draw a clear line around what FlowMCP takes responsibility for and what it deliberately leaves to the user: FlowMCP records and links the relevant Terms of Services and data licenses, but it never interprets or certifies them. The page describes that three-layer model, the optional schema fields that carry the links, and where responsibility for compliance ultimately rests. diff --git a/src/content/docs/specification/mcp-integration.md b/src/content/docs/specification/mcp-integration.md index d49b5a1..418aee0 100644 --- a/src/content/docs/specification/mcp-integration.md +++ b/src/content/docs/specification/mcp-integration.md @@ -6,16 +6,13 @@ spec_file: "19-mcp-integration.md" order: 19 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/19-mcp-integration.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/19-mcp-integration.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/19-mcp-integration.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/19-mcp-integration.md." --- - When FlowMCP runs as an MCP Server, each Tool is exposed to the agent with MCP-specific metadata that an MCP host can read before it decides whether and how to invoke the Tool. That metadata is declared once, per Tool, in a `meta` block, and the CLI/Core translates the relevant fields into MCP annotations at registration time. This page describes the `meta` block, how its fields map to MCP, and the behaviour of the search-related and loading-related fields. diff --git a/src/content/docs/specification/migration.md b/src/content/docs/specification/migration.md index 57d3af2..09ea9a8 100644 --- a/src/content/docs/specification/migration.md +++ b/src/content/docs/specification/migration.md @@ -6,16 +6,13 @@ spec_file: "08-migration.md" order: 8 section: "Specification" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/08-migration.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/08-migration.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/08-migration.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/08-migration.md." --- - This guide covers migrating schemas between FlowMCP versions in chronological order. Section 1 covers v1.2.0 to v2.0.0 migration, Section 2 covers v2.0.0 to v3.0.0, and Section 3 covers v3.0.0 to v4.0.0. diff --git a/src/content/docs/specification/output-schema.md b/src/content/docs/specification/output-schema.md index 59ee389..afafa5e 100644 --- a/src/content/docs/specification/output-schema.md +++ b/src/content/docs/specification/output-schema.md @@ -6,16 +6,13 @@ spec_file: "04-output-schema.md" order: 4 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/04-output-schema.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/04-output-schema.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/04-output-schema.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/04-output-schema.md." --- - Output schemas make tool responses predictable. By declaring the expected shape of a response at the route level, an AI client knows in advance what fields it will receive and can reason about them without parsing guesswork. The sections below cover the output declaration format, the supported types and MIME-types, the standard response envelope, how output interacts with `postRequest` handlers, and the validation rules applied to every declaration. diff --git a/src/content/docs/specification/overview.md b/src/content/docs/specification/overview.md index 26fb232..9af8ac6 100644 --- a/src/content/docs/specification/overview.md +++ b/src/content/docs/specification/overview.md @@ -6,16 +6,13 @@ spec_file: "00-overview.md" order: 0 section: "Specification" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/00-overview.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/00-overview.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/00-overview.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/00-overview.md." --- - FlowMCP is a **Tool Catalog with pre-built API templates** and a **Knowledge Base for API workflows**. It unifies access to APIs through two equal channels: diff --git a/src/content/docs/specification/parameters.md b/src/content/docs/specification/parameters.md index 1432b86..b3051c9 100644 --- a/src/content/docs/specification/parameters.md +++ b/src/content/docs/specification/parameters.md @@ -6,16 +6,13 @@ spec_file: "02-parameters.md" order: 2 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/02-parameters.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/02-parameters.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/02-parameters.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/02-parameters.md." --- - A parameter declares where a value is placed in the outgoing API request and how it is validated before the call is made. Each tool parameter pairs a `position` block (placement) with a `z` block (validation); resource parameters reuse the same pairing without a `location` field, and skill input uses a simpler shape. diff --git a/src/content/docs/specification/prefill.md b/src/content/docs/specification/prefill.md index a4caede..ecabac1 100644 --- a/src/content/docs/specification/prefill.md +++ b/src/content/docs/specification/prefill.md @@ -6,16 +6,13 @@ spec_file: "18-prefill.md" order: 18 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/18-prefill.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/18-prefill.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/18-prefill.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/18-prefill.md." --- - Skill content carries two complementary template mechanisms that the runtime processes before handing the Skill to an agent. *Placeholders* are tokens embedded directly in the content — `{{type:reference}}` — that are substituted with tool descriptions, resource references, user input, or shared-list values at resolution time. *Prefill* goes one step further: a Skill can declare tool calls in a `prefill` array that the runtime executes up front, then embeds the live results into the content via `{{prefill:...}}` tokens, so the agent receives a Skill already populated with current data. diff --git a/src/content/docs/specification/preload.md b/src/content/docs/specification/preload.md index 88bc411..0bfa9bb 100644 --- a/src/content/docs/specification/preload.md +++ b/src/content/docs/specification/preload.md @@ -6,16 +6,13 @@ spec_file: "11-preload.md" order: 11 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/11-preload.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/11-preload.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/11-preload.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/11-preload.md." --- - Some tools return data that barely moves — a full list of hospitals in a country, every memorial stone in a city, a reference table that is refreshed once a week. Re-fetching such a dataset on every call costs bandwidth and time for no benefit. The optional `preload` field lets a schema author declare that a tool's response is safe to cache and for how long, so a runtime can serve a stored copy instead of hitting the network each time. Caching always stays optional on the runtime's side: `preload` expresses intent, and the runtime decides whether to honour it. The sections below specify the field, its validation rules, the cache key derivation, the runtime cache flow, and the author guidelines for choosing a sensible time-to-live. diff --git a/src/content/docs/specification/prompt-architecture.md b/src/content/docs/specification/prompt-architecture.md index 6cab457..5398ac2 100644 --- a/src/content/docs/specification/prompt-architecture.md +++ b/src/content/docs/specification/prompt-architecture.md @@ -6,16 +6,13 @@ spec_file: "12-prompt-architecture.md" order: 12 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/12-prompt-architecture.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/12-prompt-architecture.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/12-prompt-architecture.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/12-prompt-architecture.md." --- - FlowMCP uses a two-tier prompt system to bridge deterministic tools with non-deterministic AI orchestration. **Provider-Prompts** explain how to use a single provider's tools effectively. **Agent-Prompts** compose tools from multiple providers into tested workflows. Both types use the `{{type:name}}` placeholder syntax for references and parameters. Provider-Prompts are defined in `main.prompts` with content loaded from external `.mjs` files via `contentFile`. Agent-Prompts are standalone `.mjs` files with `export const prompt = { ... }` containing inline content. diff --git a/src/content/docs/specification/resources.md b/src/content/docs/specification/resources.md index 80ba3a1..9ad1235 100644 --- a/src/content/docs/specification/resources.md +++ b/src/content/docs/specification/resources.md @@ -6,16 +6,13 @@ spec_file: "13-resources.md" order: 13 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/13-resources.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/13-resources.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/13-resources.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/13-resources.md." --- - Resources give a schema local, deterministic data access alongside its network tools. They map to the MCP `server.resource` primitive and live in `main.resources` next to `main.tools`. A resource is backed by a SQLite database (read-only in-memory or writable file-based), a remote SQLite file fetched over HTTPS, or a Markdown document — and the runtime exposes each through a small set of typed queries, with the auto-injected `runSql` and `describeTables` rounding out the query surface. Where a tool reaches out to a third-party API, a resource serves data that should always be available: reference tables, lookups, agent-collected results, and inline documentation. diff --git a/src/content/docs/specification/route-tests.md b/src/content/docs/specification/route-tests.md deleted file mode 100644 index 7d49624..0000000 --- a/src/content/docs/specification/route-tests.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: "Tests" -description: "FlowMCP v4.0.0 tests — executable documentation for tools and resources, response capture lifecycle, and output schema generation" ---- - -Specification - - -Tests are executable examples embedded in each tool and resource definition. They serve three purposes: documenting what a tool can do, providing input data to capture real API responses, and generating accurate output schemas from those responses. - -:::note -This page covers tests from the [formal specification](https://github.com/FlowMCP/flowmcp-spec). See [Output Schema](/specification/output-schema/) for how generated schemas are used. -::: - -## Purpose - -```mermaid -flowchart LR - A[Tests] --> B[Learning: what is possible] - A --> C[Execution: call real API] - C --> D[Capture: store response] - D --> E[Generate: output schema] -``` - -- **Learning instrument** — a developer or AI agent reading tests should understand the tool's capabilities by reading tests alone -- **Output schema source** — tests provide parameter values for real API calls, and captured responses are fed into the `OutputSchemaGenerator` - -## Tool Test Format - -Tests are defined as an array inside each tool definition, alongside `method`, `path`, `description`, and `parameters`: - -```javascript -tools: { - getSimplePrice: { - method: 'GET', - path: '/simple/price', - description: 'Fetch current price for one or more coins', - parameters: [ - { - position: { key: 'ids', value: '{{USER_PARAM}}', location: 'query' }, - z: { primitive: 'array()', options: [] } - }, - { - position: { key: 'vs_currencies', value: '{{USER_PARAM}}', location: 'query' }, - z: { primitive: 'string()', options: [] } - } - ], - tests: [ - { - _description: 'Single coin in single currency', - ids: ['bitcoin'], - vs_currencies: 'usd' - }, - { - _description: 'Multiple coins in multiple currencies', - ids: ['bitcoin', 'ethereum', 'solana'], - vs_currencies: 'usd,eur,gbp' - } - ] - } -} -``` - -## Resource Query Tests - -Resources can also have tests. Since resources use SQL queries instead of HTTP requests, test values correspond to query parameters: - -```javascript -resources: { - verifiedContracts: { - source: 'sqlite', - database: 'contracts.db', - queries: { - byAddress: { - description: 'Find contract by address', - sql: 'SELECT * FROM contracts WHERE address = ?', - parameters: [ - { key: 'address', type: 'string', description: 'Contract address', required: true } - ], - tests: [ - { - _description: 'Known verified contract (USDC)', - address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' - } - ] - } - } - } -} -``` - -## Test Fields - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `_description` | `string` | Yes | What this specific test demonstrates | -| `{paramKey}` | matches parameter type | Yes (per required param) | Value for each `{{USER_PARAM}}` parameter (tools) or query parameter (resources) | - -### Writing Good Descriptions - -```javascript -// Good — explains the specific scenario -{ _description: 'ERC-20 token on Ethereum mainnet', ... } -{ _description: 'Native token on Layer 2 chain (Arbitrum)', ... } -{ _description: 'Wallet with high transaction volume', ... } - -// Bad — generic, uninformative -{ _description: 'Test getTokenPrice', ... } -{ _description: 'Basic test', ... } -``` - -## Design Principles - -### 1. Express the Breadth - -Tests should cover the **range of what is possible**: - -```javascript -// Good — shows breadth of chains and token types -tests: [ - { _description: 'ERC-20 token on Ethereum', chain_id: 1, contract: '0x6982...' }, - { _description: 'Native token on Polygon', chain_id: 137, contract: '0x0000...' }, - { _description: 'Stablecoin on Arbitrum', chain_id: 42161, contract: '0xaf88...' } -] -``` - -### 2. Teach Through Examples - -Each test should teach one capability or variation. - -### 3. No Personal Data - -:::caution -Tests must never contain personal data. All test values must be publicly known, verifiable, and non-sensitive. -::: - -| Allowed | Not Allowed | -|---------|-------------| -| Public smart contract addresses | Private wallet addresses | -| Well-known token contracts (USDC, WETH) | Personal wallet addresses | -| Public blockchain data (block numbers, tx hashes) | Email addresses, names | -| Standard chain IDs (1, 137, 42161) | API keys, tokens, passwords | - -### 4. Reproducible Results - -Prefer well-established tokens/contracts over newly deployed ones, and historical data queries over latest-block queries when possible. - -## Test Count Guidelines - -| Scenario | Minimum | Recommended | -|----------|---------|-------------| -| No parameters | 1 | 1 | -| 1-2 parameters | 1 | 2-3 | -| Enum/chain parameters | 1 | 2-4 (different enum values) | -| Multiple optional parameters | 1 | 2-3 (with/without optionals) | -| Resource queries | 1 | 1-2 | - -Minimum 1 test per tool is required (validation error TST001 if missing). - -## Response Capture Lifecycle - -```mermaid -flowchart TD - A[1. Read tests from tool] --> B[2. Resolve server params from env] - B --> C[3. Execute API call per test] - C --> D[4. Record full response with metadata] - D --> E[5. Feed response to OutputSchemaGenerator] - E --> F[6. Write output schema to tool definition] -``` - -1. **Read Tests** — Extract parameter values from each test object. -2. **Resolve Server Params** — Load `requiredServerParams` from environment variables. -3. **Execute API Call** — Construct the full request and execute. A delay between calls (default: 1s) prevents rate limiting. -4. **Record Response** — Store full response with metadata (namespace, toolName, testIndex, timestamp, responseTime). -5. **Generate Output Schema** — The `OutputSchemaGenerator` analyzes `response.data` structure and produces a schema definition. -6. **Write Output Schema** — Generated schema is written to the tool's `output` field. Existing schemas can be validated against reality. - -### Captured Response Format - -```javascript -{ - namespace: 'coingecko', - toolName: 'getSimplePrice', - testIndex: 0, - _description: 'Single coin in USD', - userParams: { ids: ['bitcoin'], vs_currencies: 'usd' }, - responseTime: 234, - timestamp: '2026-02-17T10:30:00Z', - response: { - status: true, - messages: [], - data: { /* actual API response after handler transformation */ } - } -} -``` - -:::tip -The `response.data` contains data **after handler transformation**. This is critical because the output schema describes the final shape, not the raw API response. -::: - -### Capture File Structure - -``` -capture/ -└── {timestamp}/ - └── {namespace}/ - ├── {toolName}-0.json - ├── {toolName}-1.json - └── metrics.json -``` - -## Test Execution Modes - -| Mode | Description | Use Case | -|------|-------------|----------| -| **Capture** | Execute against real API, store responses | Schema development, output schema generation | -| **Validation** | Execute and compare against declared `output.schema` | Verify schemas remain accurate over time | -| **Dry-Run** | Validate test definitions without API calls | During `flowmcp validate` | - -## Validation Rules - -| Code | Severity | Rule | -|------|----------|------| -| TST001 | error | Each tool must have at least 1 test | -| TST002 | error | Each test must have a `_description` field of type string | -| TST003 | error | Each test must provide values for all required `{{USER_PARAM}}` parameters | -| TST004 | error | Test parameter values must pass the corresponding `z` validation | -| TST005 | error | Test objects must be JSON-serializable | -| TST006 | error | Test objects must only contain keys matching `{{USER_PARAM}}` parameter keys or `_description` | -| TST007 | warning | Tools with enum parameters should test multiple enum values | -| TST008 | info | Consider adding tests that demonstrate optional parameter usage | diff --git a/src/content/docs/specification/schema-format.md b/src/content/docs/specification/schema-format.md index 5eae13d..50b1197 100644 --- a/src/content/docs/specification/schema-format.md +++ b/src/content/docs/specification/schema-format.md @@ -6,16 +6,13 @@ spec_file: "01-schema-format.md" order: 1 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/01-schema-format.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/01-schema-format.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/01-schema-format.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/01-schema-format.md." --- - A FlowMCP schema is a single `.mjs` module that describes how to reach an API and turn its endpoints into tools. It splits into two named exports: a static, JSON-serializable `main` block that holds all declarative configuration, and an optional `handlers` factory that transforms requests and responses. The sections below walk through both exports, the tool and field definitions inside `main`, the naming conventions, and the constraints the runtime enforces at load time. diff --git a/src/content/docs/specification/schema-lifecycle.md b/src/content/docs/specification/schema-lifecycle.md index 212ab98..f7ad799 100644 --- a/src/content/docs/specification/schema-lifecycle.md +++ b/src/content/docs/specification/schema-lifecycle.md @@ -6,16 +6,13 @@ spec_file: "21-schema-lifecycle.md" order: 21 section: "Specification" normative: false -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/21-schema-lifecycle.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/21-schema-lifecycle.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/21-schema-lifecycle.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/21-schema-lifecycle.md." --- - Every FlowMCP schema travels a defined path from an initial idea to a production deployment, and this page is the canonical description of that path: the six lifecycle stages, the special rules for static and migrated schemas, and the policy for handling schemas where only some primitives pass. It is the recommended way to develop a schema, and where other lifecycle descriptions in the project (README files, runbooks, skill documentation) disagree, this page is authoritative. diff --git a/src/content/docs/specification/scoring-protocol.md b/src/content/docs/specification/scoring-protocol.md index a61843a..394cb4d 100644 --- a/src/content/docs/specification/scoring-protocol.md +++ b/src/content/docs/specification/scoring-protocol.md @@ -6,16 +6,13 @@ spec_file: "22-scoring-protocol.md" order: 22 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/22-scoring-protocol.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/22-scoring-protocol.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/22-scoring-protocol.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/22-scoring-protocol.md." --- - Specification for grading FlowMCP v4 schemas via LLM evaluation. Documents the data formats exchanged between the CLI and an external Grader (e.g. Claude Code harness, third-party implementation). diff --git a/src/content/docs/specification/security.md b/src/content/docs/specification/security.md index 6de5270..d2d958a 100644 --- a/src/content/docs/specification/security.md +++ b/src/content/docs/specification/security.md @@ -6,16 +6,13 @@ spec_file: "05-security.md" order: 5 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/05-security.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/05-security.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/05-security.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/05-security.md." --- - FlowMCP enforces a layered security model that prevents schema files from accessing the network, filesystem, or process environment. All potentially dangerous operations are restricted to the trusted core runtime. Dependencies are injected through a factory function pattern, and external libraries are gated by an allowlist. diff --git a/src/content/docs/specification/selections.md b/src/content/docs/specification/selections.md index 9ffa32e..cb81308 100644 --- a/src/content/docs/specification/selections.md +++ b/src/content/docs/specification/selections.md @@ -6,16 +6,13 @@ spec_file: "17-selections.md" order: 17 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/17-selections.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/17-selections.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/17-selections.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/17-selections.md." --- - **Primitive:** Selection (5th primitive) diff --git a/src/content/docs/specification/shared-lists.md b/src/content/docs/specification/shared-lists.md index a4b79d4..e14de21 100644 --- a/src/content/docs/specification/shared-lists.md +++ b/src/content/docs/specification/shared-lists.md @@ -6,16 +6,13 @@ spec_file: "03-shared-lists.md" order: 3 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/03-shared-lists.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/03-shared-lists.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/03-shared-lists.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/03-shared-lists.md." --- - Shared lists eliminate duplication of common value sets across schemas. Instead of every Etherscan schema maintaining its own chain list, they reference a single `evmChains` shared list that is versioned, validated, and centrally maintained. The sections below cover the list file format, the meta and field definitions, the dependency model between lists, how schemas reference and filter lists, how the runtime injects resolved data into handlers, and the validation rules that keep the registry consistent. diff --git a/src/content/docs/specification/skills.md b/src/content/docs/specification/skills.md index 6c2ff2f..d93145a 100644 --- a/src/content/docs/specification/skills.md +++ b/src/content/docs/specification/skills.md @@ -6,16 +6,13 @@ spec_file: "14-skills.md" order: 14 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/14-skills.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/14-skills.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/14-skills.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/14-skills.md." --- - Skills are reusable, self-contained instruction sets that an AI agent can load and follow. They map to the MCP `server.prompt` primitive and live in `.mjs` files, each with a structured `export const skill` object that pairs Markdown instructions with typed metadata. A skill declares the tools and resources it needs, the input it expects, and the output it produces, and its instructions reference those primitives through `{{tool:...}}`, `{{resource:...}}`, and `{{input:...}}` placeholders resolved at load time. diff --git a/src/content/docs/specification/tasks.md b/src/content/docs/specification/tasks.md index ae84a03..037a9b3 100644 --- a/src/content/docs/specification/tasks.md +++ b/src/content/docs/specification/tasks.md @@ -6,16 +6,13 @@ spec_file: "07-tasks.md" order: 7 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/07-tasks.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/07-tasks.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/07-tasks.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/07-tasks.md." --- - MCP Tasks describe long-running asynchronous operations — a query that takes thirty seconds to finish, a job that is submitted now and collected later. The underlying MCP protocol gives such operations a lifecycle of creation, polling, completion, and cancellation. FlowMCP does not yet model this lifecycle: task support is a reserved, forward-looking area of the specification, and this page documents what is held back and why. diff --git a/src/content/docs/specification/tests.md b/src/content/docs/specification/tests.md index 41ee9df..548b451 100644 --- a/src/content/docs/specification/tests.md +++ b/src/content/docs/specification/tests.md @@ -6,16 +6,13 @@ spec_file: "10-tests.md" order: 10 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/10-tests.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/10-tests.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/10-tests.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/10-tests.md." --- - Tests are executable examples embedded in tool and resource query definitions. For agents, tests are prompts paired with expected tool usage and content assertions. They serve three purposes: they document what a tool or resource query can do, they provide the input data needed to capture real responses, and those captured responses become the basis for generating accurate output schemas. The sections below cover the test format for tools, resources, and agents, the design principles that keep tests useful, and the response-capture lifecycle that turns a test into an output schema. diff --git a/src/content/docs/specification/validation-rules.md b/src/content/docs/specification/validation-rules.md index c8238ea..5c537e6 100644 --- a/src/content/docs/specification/validation-rules.md +++ b/src/content/docs/specification/validation-rules.md @@ -6,16 +6,13 @@ spec_file: "09-validation-rules.md" order: 9 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/09-validation-rules.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/09-validation-rules.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/09-validation-rules.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/09-validation-rules.md." --- - Every validation rule that `flowmcp schema-check` enforces carries a code, a severity, and a one-line description. Rather than collect those rules into a single distant list, the specification keeps each family of rules next to the feature it governs — resource rules live with the resource spec, skill rules with the skill spec, and so on. This page is the wayfinder for that arrangement: it names each rule family, explains its code prefix, and links straight to the section where the rules are defined and explained. diff --git a/src/content/docs/specification/validation-strategy.md b/src/content/docs/specification/validation-strategy.md index da19fb7..3150991 100644 --- a/src/content/docs/specification/validation-strategy.md +++ b/src/content/docs/specification/validation-strategy.md @@ -6,16 +6,13 @@ spec_file: "20-validation-strategy.md" order: 20 section: "Specification" normative: true -source_commit: "236dbb3" -source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/236dbb3/spec/v4.3.0/20-validation-strategy.md" -generated_at: "2026-06-21T11:44:44.465Z" +source_commit: "42b4603" +source_url: "https://github.com/FlowMCP/flowmcp-spec/blob/42b4603/spec/v4.3.0/20-validation-strategy.md" +generated_at: "2026-06-21T01:06:21.418Z" generated_from: "spec/v4.3.0/20-validation-strategy.md" generator: "scripts/generate-docs-payload.mjs" edit_warning: "This file is auto-generated. Source: spec/v4.3.0/20-validation-strategy.md." --- - Validation in FlowMCP works in two layers. A **deterministic** layer checks structural correctness — that the schema is well-formed and every primitive declares the fields it must. A **probabilistic** layer adds an LLM-based quality judgement on top of a structurally clean schema. Together the two layers produce a **Grade Report** that assigns a single letter grade (A–F), which is the record this page defines. diff --git a/src/pages/404.astro b/src/pages/404.astro index ab60a62..bbddc10 100644 --- a/src/pages/404.astro +++ b/src/pages/404.astro @@ -39,7 +39,7 @@
  • → Quickstart — What is FlowMCP?
  • → Concepts — Schemas
  • → Specification — Overview
    • -
  • → Reference — CLI Usage
    • +
  • → Quickstart — CLI Setup
  • → Blog
    • diff --git a/src/templates/about/faq.template.md b/src/templates/about/faq.template.md deleted file mode 100644 index a805d34..0000000 --- a/src/templates/about/faq.template.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: FAQ -description: Frequently asked questions about FlowMCP — installation, MCP clients, schemas, contributions. ---- - -
    -What is FlowMCP exactly? - -FlowMCP is a schema library + engine that normalises data sources into AI-callable tools. The library currently contains {{stats.count_schemas}} production-ready schemas (v4) covering {{stats.count_unique_datasources}} data sources. The engine routes calls, validates inputs/outputs, and handles authentication. AI agents call FlowMCP; FlowMCP calls the underlying APIs. - -
    - -
    -Do I need an MCP-compatible client? - -No. FlowMCP is **CLI-first**. The MCP server mode is optional. If you have a client that supports dynamic tool loading, MCP works — otherwise the CLI is the preferred entry point. - -
    - -
    -What does CLI-first mean in practice? - -You run `flowmcp call . '{...}'` from your terminal, an LLM call, or a Node/Python script. Tools are loaded on demand — no need to keep {{stats.count_tools}} tools in context. - -
    - -
    -Where do API keys live? - -API keys live in `~/.flowmcp/.env`, optionally with project overrides. The AI never sees a key — it only sees calls and responses. This is intentional: if an AI made direct REST calls, it would expose keys. - -
    - -
    -How do I add a new schema? - -See the [Specification](/specification/) and `repos/flowmcp-schemas-private` for the schema-creation guide. Validation rules have explicit IDs (e.g. RES001). PRs go to the schemas repo with tests. - -
    - -
    -Can I run FlowMCP offline? - -Yes — for schemas that hit local resources (e.g. the `geo-gtfs-toolkit` add-on with a converted SQLite DB). For schemas calling remote APIs, you still need network access. - -
    - -
    -What is the spec version status? - -FlowMCP currently supports the **v4** specification (active) and **v4.1** add-on extensions (e.g. `geo-gtfs-toolkit`). Older versions (v3, v2, v1.x) remain loadable for backward compatibility but receive no new schemas. - -
    - -
    -Why is FlowMCP "MCP" if it is CLI-first? - -The name dates from the project's start as an MCP server experiment. The substance shifted toward a CLI-first schema layer; the name persists for continuity with the MCP ecosystem. - -
    - -
    -Where can I report issues? - -GitHub Issues per repo. Find the most relevant repository under [github.com/FlowMCP](https://github.com/FlowMCP) and open an issue there. For schema-related questions, use `flowmcp-schemas`. For CLI bugs, use `flowmcp-cli`. - -
    - -
    -What is the v4 Self-Contained Skill Pattern? - -Skills bring their own parameter reference along — schema data goes **before** workflow instructions. In a lab test, skills with full parameter/enum/example info hit 5/5 success against LLMs; skills with name + description only hit 0/5. The pattern is documented in the v4 specification. - -
    - -
    -Are FlowMCP schemas free to use? - -Yes, MIT licensed. Some underlying APIs require keys (you supply); the data they return follows their own license — e.g. GTFS feeds under CC-BY 4.0 require attribution in your output. FlowMCP exposes that attribution in the response. - -
    diff --git a/src/templates/about/index.template.mdx b/src/templates/about/index.template.mdx index 7a85e7c..f8c5a2c 100644 --- a/src/templates/about/index.template.mdx +++ b/src/templates/about/index.template.mdx @@ -6,9 +6,9 @@ description: What FlowMCP is, why it exists, and where it stands today. About {/* PAGEFIND-META-END */} -> *FlowMCP normalises hundreds of data sources into a searchable library of AI-ready tools — so your agents can search, combine, and answer without turning you into an integrations maintainer.* +> *FlowMCP is a schema format for standardising data-source access — write the connection to an API once, and every AI agent reuses it through one uniform interface.* -FlowMCP started as a way to attach multiple data sources to a single MCP server. Today it is a schema library — **{{stats.count_schemas}} production-ready definitions, {{stats.count_unique_datasources}} data sources, {{stats.count_tools}} callable tools** — all routed through one auditable engine. AI agents call FlowMCP, never the underlying APIs directly. Your API keys stay in your control. +FlowMCP started as a way to attach multiple data sources to a single MCP server. Today it is a **format**: a way to describe, normalise, and unify the tools an AI agent uses to reach a data source. A schema is written once and reused everywhere, so the model never has to re-figure-out how an API connects. The request can be reshaped before and after the call, so tools from very different sources end up looking alike to the model — and the schema is kept separate from its grading and its security test, so you can load a schema and run the security check on its own. AI agents call FlowMCP, never the underlying APIs directly, and your API keys stay in your control. ## What FlowMCP is — and isn't @@ -17,7 +17,7 @@ FlowMCP started as a way to attach multiple data sources to a single MCP server. | Aspect | Description | |--------|-------------| | **Primitive idea** | A flow of data — from heterogeneous sources, through normalised schemas, into AI pipelines | -| **Schema library** | {{stats.count_schemas}} schemas (v4 production), {{stats.count_unique_datasources}} data sources, {{stats.count_tools}} tool routes | +| **Schema format** | One declaration shape for any data source; the same format drives the CLI, MCP server mode, and the add-on toolkits | | **Primary use** | CLI tool — no MCP client holds {{stats.count_tools}} tools in context, the CLI loads them dynamically | | **Secondary use** | MCP server mode still supported, but not the default | | **Key isolation** | Keys live in FlowMCP, never in the AI context — the AI sees calls and answers, never credentials | @@ -30,7 +30,8 @@ FlowMCP started as a way to attach multiple data sources to a single MCP server. | Misconception | Reality | |---------------|---------| -| "An MCP server" | No — CLI-first. MCP server mode is optional. | +| "An MCP server" | No — a format. MCP server mode is one optional consumer of it; the CLI is the default. | +| "A Swagger / OpenAPI spec" | More than that. Swagger describes a single API; FlowMCP unifies access *across* sources — reshaping the request before and after the call, and keeping schema, grading, and security separate. | | "A crypto library" | Started there, broadened with open data since October 2025. | | "An API wrapper collection" | No — the engine is central, schemas are thin declarations. One engine audit covers thousands of endpoints. | | "An API key manager" | Not primary. Key management is a side effect of separating AI from key. | @@ -58,8 +59,8 @@ FlowMCP makes this preparation **once, for all**: Two scenarios that show FlowMCP + AI in action — not how to build an agent, but how FlowMCP turns scattered data into one answer. -- **Deep Research** — A research tool or planning software connects an agent. The agent queries FlowMCP for relevant data sources across open data portals, government APIs, and crypto catalogs in seconds. [Read full case →](/introduction/use-cases/#use-case-1-deep-research) -- **Mobility — Catching the Connection** — A live trip planner combines static GTFS (via the `geo-gtfs-toolkit` v4.1 add-on) with real-time delay data. One CLI call, one answer. [Read full case →](/introduction/use-cases/#use-case-2-mobility--catching-the-connection) +- **Deep Research** — A research tool or planning software connects an agent. The agent queries FlowMCP for relevant data sources across open data portals, government APIs, and crypto catalogs in seconds. +- **Mobility — Catching the Connection** — A live trip planner combines static GTFS (via the `geo-gtfs-toolkit` v4.1 add-on) with real-time delay data. One CLI call, one answer. ## Production posture diff --git a/src/templates/concepts/schemas.template.md b/src/templates/concepts/schemas.template.md index ffd1344..41ef71e 100644 --- a/src/templates/concepts/schemas.template.md +++ b/src/templates/concepts/schemas.template.md @@ -6,6 +6,8 @@ description: What a FlowMCP schema is, how it is structured, and how the schema Concepts +The schema is the core building block of FlowMCP. This page explains what a schema is, how it is structured from primitives, and how the schema inventory is organised. + ## What is a Schema? A schema is the complete blueprint for accessing a single data provider — for example the German Weather Service, Deutsche Bahn, or a sharing system like nextbike. One schema per provider, multiple tools per schema. The schema translates between the provider's API and the AI agent, so the agent can query the data in a structured way without having to read the API documentation itself. diff --git a/src/templates/de/about/faq.template.md b/src/templates/de/about/faq.template.md deleted file mode 100644 index 28e6f55..0000000 --- a/src/templates/de/about/faq.template.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Haeufige Fragen -description: Antworten zu Installation, MCP-Clients, Schemas und Beitraegen. ---- - -
    -Was ist FlowMCP genau? - -FlowMCP ist eine Schema-Library + Engine, die Datenquellen zu AI-aufrufbaren Tools normalisiert. Die Library enthaelt aktuell {{stats.count_schemas}} produktionsreife Schemas (v4) ueber {{stats.count_unique_datasources}} Datenquellen. Die Engine routet Calls, validiert Inputs/Outputs und handhabt Authentifizierung. AI-Agenten rufen FlowMCP; FlowMCP ruft die zugrundeliegenden APIs. - -
    - -
    -Brauche ich einen MCP-kompatiblen Client? - -Nein. FlowMCP ist **CLI-First**. Der MCP-Server-Modus ist optional. Wenn dein Client dynamisches Tool-Loading unterstuetzt, funktioniert MCP — sonst ist die CLI der bevorzugte Einstieg. - -
    - -
    -Was bedeutet CLI-First konkret? - -Du rufst `flowmcp call . '{...}'` aus deinem Terminal, einem LLM-Call oder einem Node/Python-Script. Tools werden bei Bedarf geladen — keine Notwendigkeit, {{stats.count_tools}} Tools im Kontext zu halten. - -
    - -
    -Wo leben API-Keys? - -API-Keys leben in `~/.flowmcp/.env`, optional mit Projekt-Overrides. Die AI sieht nie einen Key — nur Calls und Antworten. Das ist Absicht: bei direkten REST-Calls aus der AI heraus wuerden Keys exposed. - -
    - -
    -Wie fuege ich ein neues Schema hinzu? - -Siehe [Specification](/specification/) und `repos/flowmcp-schemas-private` fuer den Schema-Creation-Guide. Validation-Rules haben explizite IDs (z.B. RES001). PRs gehen ins Schemas-Repo mit Tests. - -
    - -
    -Kann ich FlowMCP offline nutzen? - -Ja — fuer Schemas mit lokalen Ressourcen (z.B. das `geo-gtfs-toolkit`-Add-on mit konvertierter SQLite-DB). Fuer Schemas, die Remote-APIs callen, brauchst du weiter Netz. - -
    - -
    -Was ist der Spec-Versions-Status? - -FlowMCP unterstuetzt aktuell die **v4**-Spezifikation (aktiv) und **v4.1**-Add-on-Erweiterungen (z.B. `geo-gtfs-toolkit`). Aeltere Versionen (v3, v2, v1.x) bleiben aus Kompatibilitaetsgruenden ladbar, erhalten aber keine neuen Schemas. - -
    - -
    -Warum heisst FlowMCP "MCP", wenn es CLI-First ist? - -Der Name kommt vom Projektstart als MCP-Server-Experiment. Die Substanz hat sich Richtung CLI-First-Schema-Layer verschoben; der Name bleibt fuer Kontinuitaet mit dem MCP-Oekosystem. - -
    - -
    -Wo melde ich Issues? - -GitHub Issues pro Repo. Finde das passende Repository unter [github.com/FlowMCP](https://github.com/FlowMCP) und oeffne dort ein Issue. Fuer Schema-Fragen: `flowmcp-schemas`. Fuer CLI-Bugs: `flowmcp-cli`. - -
    - -
    -Was ist das v4 Self-Contained Skill Pattern? - -Skills bringen ihre eigene Parameter-Referenz mit — Schema-Daten stehen **vor** Workflow-Instruktionen. In einem Labortest erreichten Skills mit vollen Parameter/Enum/Beispiel-Infos 5/5 Erfolg gegen LLMs; Skills mit nur Name + Beschreibung 0/5. Das Pattern ist in der v4-Spec dokumentiert. - -
    - -
    -Sind FlowMCP-Schemas frei nutzbar? - -Ja, MIT-lizensiert. Manche APIs brauchen Keys (du lieferst sie); die zurueckgegebenen Daten folgen deren Lizenz — z.B. GTFS-Feeds unter CC-BY 4.0 brauchen Attribution im Output. FlowMCP zeigt diese Attribution in der Response. - -
    diff --git a/src/templates/de/about/index.template.mdx b/src/templates/de/about/index.template.mdx index 6d7741e..1965985 100644 --- a/src/templates/de/about/index.template.mdx +++ b/src/templates/de/about/index.template.mdx @@ -6,9 +6,9 @@ description: Was FlowMCP ist, warum es existiert, und wo es heute steht. Ueber FlowMCP {/* PAGEFIND-META-END */} -> *FlowMCP normalisiert hunderte Datenquellen zu einer durchsuchbaren Library aus AI-bereiten Tools — damit deine Agenten suchen, kombinieren und antworten können, ohne dass du sie zu Integrations-Maintainern machst.* +> *FlowMCP ist ein Schema-Format zur Standardisierung des Datenquellen-Zugangs — den Anschluss an eine API einmal schreiben, und jeder KI-Agent nutzt ihn über ein einheitliches Interface wieder.* -FlowMCP begann als Versuch, mehrere Datenquellen an einen einzigen MCP-Server anzubinden. Heute ist es eine Schema-Library — **{{stats.count_schemas}} produktionsreife Definitionen, {{stats.count_unique_datasources}} Datenquellen, {{stats.count_tools}} aufrufbare Tools** — alle ueber eine zentrale, auditierbare Engine geleitet. AI-Agenten rufen FlowMCP — nie die zugrundeliegenden APIs direkt. Deine API-Keys bleiben in deiner Kontrolle. +FlowMCP begann als Versuch, mehrere Datenquellen an einen einzigen MCP-Server anzubinden. Heute ist es ein **Format**: eine Art, die Tools zu beschreiben, zu normalisieren und zu vereinheitlichen, mit denen ein KI-Agent eine Datenquelle erreicht. Ein Schema wird einmal geschrieben und überall wiederverwendet, sodass das Modell nie neu herausfinden muss, wie eine API sich anschließt. Der Request kann vor und nach dem Aufruf umgeformt werden, sodass Tools sehr unterschiedlicher Quellen für das Modell gleich aussehen — und das Schema bleibt getrennt von seinem Grading und seinem Security-Test, sodass du ein Schema laden und den Security-Check separat fahren kannst. KI-Agenten rufen FlowMCP, nie die zugrundeliegenden APIs direkt, und deine API-Keys bleiben in deiner Kontrolle. ## Was FlowMCP ist — und nicht ist @@ -17,7 +17,7 @@ FlowMCP begann als Versuch, mehrere Datenquellen an einen einzigen MCP-Server an | Aspekt | Beschreibung | |--------|--------------| | **Primitive Idee** | Ein Fluss von Daten — aus heterogenen Quellen, durch normalisierte Schemas, in AI-Pipelines | -| **Schema-Library** | {{stats.count_schemas}} Schemas (v4-Produktion), {{stats.count_unique_datasources}} Datenquellen, {{stats.count_tools}} Tool-Routes | +| **Schema-Format** | Eine Deklarations-Form für jede Datenquelle; dasselbe Format treibt die CLI, den MCP-Server-Modus und die Add-on-Toolkits | | **Primaerer Use** | CLI-Tool — kein MCP-Client haelt {{stats.count_tools}} Tools im Kontext, die CLI laedt sie dynamisch | | **Sekundaerer Use** | MCP-Server-Modus weiter unterstuetzt, aber nicht der Default | | **Key-Isolation** | Keys leben in FlowMCP, nie im AI-Kontext — die AI sieht Calls und Antworten, nie Credentials | @@ -30,7 +30,8 @@ FlowMCP begann als Versuch, mehrere Datenquellen an einen einzigen MCP-Server an | Missverstaendnis | Realitaet | |------------------|-----------| -| "Ein MCP-Server" | Nein — CLI-First. MCP-Server-Modus ist optional. | +| "Ein MCP-Server" | Nein — ein Format. Der MCP-Server-Modus ist ein optionaler Konsument davon; die CLI ist der Default. | +| "Eine Swagger-/OpenAPI-Spec" | Mehr als das. Swagger beschreibt eine einzelne API; FlowMCP vereinheitlicht den Zugang *über* Quellen hinweg — formt den Request vor und nach dem Aufruf um und haelt Schema, Grading und Security getrennt. | | "Eine Krypto-Library" | Begann dort, ist seit Oktober 2025 mit Open Data deutlich breiter. | | "Eine API-Wrapper-Sammlung" | Nein — Engine ist zentral, Schemas sind duenne Deklarationen. Ein Audit der Engine deckt Tausende Endpunkte ab. | | "Ein API-Key-Manager" | Nicht primaer. Key-Management ist Nebenprodukt der Trennung AI ↔ Key. | @@ -58,8 +59,8 @@ FlowMCP macht diese Vorbereitung **einmal, fuer alle**: Zwei Szenarien, die FlowMCP + AI im Einsatz zeigen — nicht wie man einen Agent baut, sondern wie FlowMCP aus verstreuten Daten eine Antwort macht. -- **Deep Research** — Eine Recherche- oder Planungssoftware bindet einen Agent an. Der Agent fragt FlowMCP nach passenden Datenquellen ueber Open-Data-Portale, Behoerden-APIs und Krypto-Kataloge — in Sekunden. [Voller Case →](/de/introduction/use-cases/#use-case-1-deep-research) -- **Mobility — Anschluss erreichen** — Ein Live-Reiseplaner kombiniert statische GTFS-Daten (ueber das `geo-gtfs-toolkit` v4.1 Add-on) mit Echtzeit-Verspaetungen. Ein CLI-Call, eine Antwort. [Voller Case →](/de/introduction/use-cases/#use-case-2-mobility--anschluss-erreichen) +- **Deep Research** — Eine Recherche- oder Planungssoftware bindet einen Agent an. Der Agent fragt FlowMCP nach passenden Datenquellen ueber Open-Data-Portale, Behoerden-APIs und Krypto-Kataloge — in Sekunden. +- **Mobility — Anschluss erreichen** — Ein Live-Reiseplaner kombiniert statische GTFS-Daten (ueber das `geo-gtfs-toolkit` v4.1 Add-on) mit Echtzeit-Verspaetungen. Ein CLI-Call, eine Antwort. ## Production-Posture diff --git a/src/templates/de/concepts/schemas.template.md b/src/templates/de/concepts/schemas.template.md index 54e6cb9..f871127 100644 --- a/src/templates/de/concepts/schemas.template.md +++ b/src/templates/de/concepts/schemas.template.md @@ -6,6 +6,8 @@ description: Was ein FlowMCP-Schema ist, wie es aufgebaut ist und wie das Schema Concepts +Das Schema ist der zentrale Baustein von FlowMCP. Diese Seite erklaert, was ein Schema ist, wie es aus Primitiven aufgebaut ist und wie das Schema-Inventar organisiert ist. + ## Was ist ein Schema? Ein Schema ist der vollstaendige Bauplan fuer den Zugriff auf einen einzelnen Datenanbieter — zum Beispiel den Deutschen Wetterdienst, die Deutsche Bahn oder ein Sharing-System wie nextbike. Ein Schema pro Anbieter, mehrere Tools pro Schema. Das Schema uebersetzt zwischen der API des Anbieters und dem KI-Agenten, sodass der Agent die Daten strukturiert abfragen kann, ohne die API-Dokumentation selbst lesen zu muessen. diff --git a/src/templates/schemas-and-sources.template.md b/src/templates/schemas-and-sources.template.md deleted file mode 100644 index c8bb13b..0000000 --- a/src/templates/schemas-and-sources.template.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Schemas & Sources -description: The three layers of FlowMCP — engine, schemas, and data operators — and why FlowMCP neither publishes nor displays schemas. ---- - -FlowMCP is built from three layers that are easy to confuse but stay strictly separate. Keeping them apart is the key to understanding what FlowMCP is responsible for and what it is not. - -## Engine, Schemas, and Data Operators - -The **engine** is the part FlowMCP builds and maintains. It is the Core library and the CLI that load a schema, sign the request, call the source, and normalize the response. The engine is MIT-licensed, open source, and the same audit covers every call that flows through it. - -A **schema** is a thin declaration that tells the engine how to reach one data source and how to shape its response. Schemas are community contributions: anyone can write one for an API or dataset. They are not part of the engine, and a schema can be added, replaced, or removed without touching the engine at all. - -A **data operator** is whoever runs the API or publishes the dataset behind a schema. They decide their own Terms of Service, data license, and rate limits. FlowMCP has no control over that layer — it only passes the call through and returns the answer. - -These three layers never merge. The engine moves data, schemas describe sources, and operators own the data. Confusing them is the most common source of misunderstanding about what FlowMCP does. - -## What FlowMCP Does Not Do - -FlowMCP **does not publish schemas, and it does not show schemas on this website.** There is no catalog page, no schema browser, and no hosted list of sources here. Schemas live in their own repositories and are loaded by the CLI on demand; the website explains the engine and the model, not the individual schemas. - -Because the data operators own the source and its terms, FlowMCP also makes no judgment about them. We record a few neutral facts where a provider publishes them — the Terms of Service URL (`meta.termsOfService`), the date we last checked it (`meta.termsOfServiceCheckedAt`), and the data license name when one is stated (`meta.dataLicenseName`) — and we link out to the original. We do not classify those terms, interpret them, or advise on commercial use. Reviewing a provider's Terms of Service, rate limits, and data license before you rely on a source remains your responsibility, and FlowMCP makes no warranty about fitness for any purpose. - -## See Also - -- [Specification: License & ToS ({{spec.specDir}}/23-license-and-tos.md)](https://github.com/FlowMCP/flowmcp-spec/blob/main/{{spec.specDir}}/23-license-and-tos.md) -- [DISCLAIMER.md in flowmcp-core](https://github.com/FlowMCP/flowmcp-core/blob/main/DISCLAIMER.md) -- [DISCLAIMER.md in flowmcp-cli](https://github.com/FlowMCP/flowmcp-cli/blob/main/DISCLAIMER.md) From 96095b5fa17444f78b6711cbfe6a23afacb0c1ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=CE=B1=CE=B7dr3=CE=B15=20=C9=AE=CE=B1=CE=B7=C9=A6=D6=85l?= =?UTF-8?q?=CA=903=CA=80?= <2878033+a6b8@users.noreply.github.com> Date: Sun, 21 Jun 2026 14:08:59 +0200 Subject: [PATCH 2/2] Update Playwright tests for reduced nav #124 Memo 142 removed FAQ/Use-Cases/Schemas&Sources/guides/Reference/Ecosystem; move those routes to FORBIDDEN_ROUTES, repoint copy-markdown to quickstart, fix hero-headline + sidebar-group + link-consistency asserts, AI-Engineer persona -> Specification. Full local suite 151 passed / 0 failed. --- tests/playwright/copy-markdown.spec.mjs | 12 ++++--- tests/playwright/navigation.spec.mjs | 11 +++--- tests/playwright/personas.spec.mjs | 8 +++-- tests/playwright/phase-9-routes.mjs | 46 ++++++++----------------- 4 files changed, 33 insertions(+), 44 deletions(-) diff --git a/tests/playwright/copy-markdown.spec.mjs b/tests/playwright/copy-markdown.spec.mjs index c096992..da66a56 100644 --- a/tests/playwright/copy-markdown.spec.mjs +++ b/tests/playwright/copy-markdown.spec.mjs @@ -21,8 +21,10 @@ test.describe( 'Header copy-markdown button', () => { await context.grantPermissions( [ 'clipboard-read', 'clipboard-write' ] ) } ) - test( 'A. exactly one header copy button on Hackathon Kit', async ( { page } ) => { - await page.goto( '/guides/hackathon-kit/' ) + // Memo 142: the Hackathon Kit guide was removed; the header copy button is a + // generic per-page feature, so these assert it on a surviving content page. + test( 'A. exactly one header copy button on Quickstart', async ( { page } ) => { + await page.goto( '/quickstart/quickstart/' ) const buttons = page.locator( 'button[data-header-copy]' ) await expect( buttons ).toHaveCount( 1 ) @@ -30,7 +32,7 @@ test.describe( 'Header copy-markdown button', () => { } ) test( 'B. click copies page markdown and shows feedback', async ( { page } ) => { - await page.goto( '/guides/hackathon-kit/' ) + await page.goto( '/quickstart/quickstart/' ) const button = page.locator( 'button[data-header-copy]' ).first() await button.click() @@ -39,11 +41,11 @@ test.describe( 'Header copy-markdown button', () => { const clipboardText = await page.evaluate( () => navigator.clipboard.readText() ) expect( clipboardText.length ).toBeGreaterThan( 500 ) - expect( clipboardText.toLowerCase() ).toContain( 'hackathon' ) + expect( clipboardText.toLowerCase() ).toContain( 'flowmcp' ) } ) test( 'C. button state reverts after 2s', async ( { page } ) => { - await page.goto( '/guides/hackathon-kit/' ) + await page.goto( '/quickstart/quickstart/' ) const button = page.locator( 'button[data-header-copy]' ).first() await button.click() diff --git a/tests/playwright/navigation.spec.mjs b/tests/playwright/navigation.spec.mjs index 56b4578..a4ee5dc 100644 --- a/tests/playwright/navigation.spec.mjs +++ b/tests/playwright/navigation.spec.mjs @@ -14,12 +14,14 @@ test.describe( 'Navigation (Pencil-Layout REV-15)', () => { await expect( sidebar.getByText( /Get Started/i ).first() ).toBeAttached() await expect( sidebar.getByText( /Concepts/i ).first() ).toBeAttached() await expect( sidebar.getByText( /Specification/i ).first() ).toBeAttached() - await expect( sidebar.getByText( /Reference/i ).first() ).toBeAttached() + // Memo 142: Reference group removed; Grading is a surviving nav group. + await expect( sidebar.getByText( /Grading/i ).first() ).toBeAttached() } ) test( '2. Landing zeigt Pencil-Hero + LogoStrip + StatsBar', async ( { page } ) => { await page.goto( '/' ) - await expect( page.getByText( /Unified access to any data source/i ).first() ).toBeVisible() + // Memo 142: hero headline pivot to the schema-format positioning. + await expect( page.getByText( /Schema-driven data access/i ).first() ).toBeVisible() await expect( page.getByText( /Connects to/i ).first() ).toBeVisible() // Stats are dynamic (from refs.json); assert numeric pattern instead of fixed value await expect( page.getByText( /\b\d{3,}\b/ ).first() ).toBeVisible() @@ -73,17 +75,16 @@ test.describe( 'Navigation (Pencil-Layout REV-15)', () => { } ) test( '10. Linkkonsistenz — keine 404 von Hauptpfaden', async ( { page } ) => { + // Memo 142: removed pages (faq, reference/cli, schemas-and-sources) dropped; + // they 404 by design and are covered in phase-9 FORBIDDEN_ROUTES instead. const routes = [ '/about/', - '/about/faq/', '/concepts/schemas/', '/concepts/tools/', '/concepts/primitives/', '/concepts/clients/', '/specification/overview/', - '/reference/cli/', '/blog/', - '/schemas-and-sources/', ] for( const route of routes ) { const response = await page.goto( route ) diff --git a/tests/playwright/personas.spec.mjs b/tests/playwright/personas.spec.mjs index 956fc02..dd7a2d5 100644 --- a/tests/playwright/personas.spec.mjs +++ b/tests/playwright/personas.spec.mjs @@ -9,11 +9,13 @@ test.describe( 'Persona-E2E-Pfade (Memo 045 REV-15 Kap. 2)', () => { await expect( heading ).toContainText( /Quickstart/i ) } ) - test( 'AI-Engineer — Landing -> Reference', async ( { page } ) => { + test( 'AI-Engineer — Landing -> Specification', async ( { page } ) => { + // Memo 142: the Reference section was removed; the format Specification is + // the AI-engineer's canonical destination now. await page.goto( '/' ) - await page.goto( '/reference/core-methods/' ) + await page.goto( '/specification/overview/' ) const heading = page.locator( 'h1' ).first() - await expect( heading ).toContainText( /Core.*Methods/i ) + await expect( heading ).toContainText( /Overview/i ) } ) test( 'Schema-Maintainer — Landing -> Specification -> Schema-Format', async ( { page } ) => { diff --git a/tests/playwright/phase-9-routes.mjs b/tests/playwright/phase-9-routes.mjs index fb23487..c7478b1 100644 --- a/tests/playwright/phase-9-routes.mjs +++ b/tests/playwright/phase-9-routes.mjs @@ -24,23 +24,20 @@ // Optional-Route (QS5 Discovery, derzeit nicht in Sidebar): /guides/schema-creation/ +// Memo 142: the docs site was reduced to the format/spec core. FAQ, Use Cases, +// Schemas & Sources, the guides (Hackathon Kit / Agent Creation / GTFS Pilot), the +// whole Reference section and the whole Ecosystem section were removed (moved to +// .trash). Those routes now live in FORBIDDEN_ROUTES (Block 2: 404/redirect = PASS). const EN_ROUTES = [ // About-Gruppe { path: '/about/', expectedMarker: 'About FlowMCP', group: 'About', locale: 'en' }, - { path: '/about/faq/', expectedMarker: 'FAQ', group: 'About', locale: 'en' }, - { path: '/introduction/use-cases/', expectedMarker: 'Use Cases', group: 'About', locale: 'en' }, - { path: '/schemas-and-sources/', expectedMarker: 'Schemas & Sources', group: 'About', locale: 'en' }, // Get-Started-Gruppe { path: '/quickstart/quickstart/', expectedMarker: 'Quickstart', group: 'Get Started', locale: 'en' }, { path: '/introduction/for-llms/', expectedMarker: 'For LLMs', group: 'Get Started', locale: 'en' }, - { path: '/guides/hackathon-kit/', expectedMarker: 'Hackathon Kit', group: 'Get Started', locale: 'en' }, - { path: '/guides/agent-creation/', expectedMarker: 'Agent Creation', group: 'Get Started', locale: 'en' }, - { path: '/guides/gtfs-pilot/', expectedMarker: 'GTFS Pilot', group: 'Get Started', locale: 'en' }, // Concepts { path: '/concepts/schemas/', expectedMarker: 'Schemas', group: 'Concepts', locale: 'en' }, - { path: '/concepts/tools/', expectedMarker: 'Tools', group: 'Concepts', locale: 'en' }, { path: '/concepts/primitives/', expectedMarker: 'Primitives', group: 'Concepts', locale: 'en' }, { path: '/concepts/clients/', expectedMarker: 'Clients', group: 'Concepts', locale: 'en' }, @@ -51,15 +48,6 @@ const EN_ROUTES = [ { path: '/specification/resources/', expectedMarker: 'Resources', group: 'Specification', locale: 'en' }, { path: '/specification/validation-rules/', expectedMarker: 'Validation', group: 'Specification', locale: 'en' }, - // Reference - { path: '/reference/cli/', expectedMarker: 'CLI', group: 'Reference', locale: 'en' }, - { path: '/reference/core-methods/', expectedMarker: 'Core', group: 'Reference', locale: 'en' }, - { path: '/reference/mcp-server/', expectedMarker: 'MCP Server', group: 'Reference', locale: 'en' }, - - // Ecosystem - { path: '/ecosystem/agentprobe/', expectedMarker: 'AgentProbe', group: 'Ecosystem', locale: 'en' }, - { path: '/ecosystem/x402/', expectedMarker: 'x402', group: 'Ecosystem', locale: 'en' }, - // Blog { path: '/blog/', expectedMarker: 'Blog', group: 'Blog', locale: 'en' }, @@ -68,24 +56,16 @@ const EN_ROUTES = [ ] -// DE-Mirror: gleiche Pfade mit Prefix /de/. Optional-Flag uebernommen. -// Die Marker werden gelockert (nutzen kleinere Tokens), weil viele DE-Seiten -// neu hinzugefuegte Content-Items (hackathon-kit, agent-creation, gtfs-pilot, -// schemas-and-sources) keine DE-Uebersetzung haben und Starlight diese als -// 404 ausliefert — diese Routen werden als optional markiert. -const DE_ONLY_OPTIONAL_PATHS = [ - '/about/faq/', // DE-Faq existiert, aber Marker variiert - '/schemas-and-sources/', // DE-Mirror existiert +// Memo 142: routes removed from the site (and their DE mirrors). They now 404 +// (or redirect, for the ones with a repointed legacy redirect). Block 2 accepts +// 404 / 3xx / 200+meta-refresh → these verify the reduction landed. +const MEMO_142_REMOVED_PATHS = [ + '/about/faq/', '/introduction/use-cases/', - '/introduction/for-llms/', - '/quickstart/quickstart/', + '/schemas-and-sources/', '/guides/hackathon-kit/', '/guides/agent-creation/', '/guides/gtfs-pilot/', - '/concepts/schemas/', - '/concepts/tools/', - '/concepts/primitives/', - '/concepts/clients/', '/reference/cli/', '/reference/core-methods/', '/reference/mcp-server/', @@ -144,7 +124,11 @@ const FORBIDDEN_ROUTES = [ '/de/concepts/schemas-skills/', '/de/concepts/schemas-tools/', '/de/concepts/schema-catalog/', - '/de/concepts/tag-search/' + '/de/concepts/tag-search/', + + // Memo 142: reduced pages (EN + DE mirrors) — removed from the site. + ...MEMO_142_REMOVED_PATHS, + ...MEMO_142_REMOVED_PATHS.map( ( p ) => `/de${ p }` ) ]