FlowMCP CLI工具

FlowMCP命令行界面

用于开发、验证和管理FlowMCP模式的命令行工具。

描述

FlowMCP CLI是一个开发工具，用于处理FlowMCP模式-结构化的API定义，使AI代理能够与外部服务交互。CLI直接从您在中列出的文件夹中读取模式 schemaFolders[] （一个全局配置），使每个工具都可以立即调用（无激活步骤），并提供模式验证和实时API测试。

MCP服务器： flowmcp run （stdio MCP服务器）和 @modelcontextprotocol/sdk 依赖关系已被删除。要通过MCP提供模式，请使用 mcp-agent-server 或者在进程中嵌入核心v4外观(FlowMCP.loadSchema() + FlowMCP.prepareServerTool()).

建筑学

flowchart TD
    A[~/.flowmcp/config.json] --> B{schemaFolders Array}
    B --> C[name + path -> path/providers]
    C --> D[Loader: all tools immediately available]
    D --> E{requiredServerParams vs ~/.flowmcp/.env}
    E -->|key present| F[tool active]
    E -->|key missing| G[tool disabled: missing KEY visible]
    F --> H[search / list / call]
    G --> H

一个全局配置(~/.flowmcp/config.json)按路径直接指向您的模式文件夹。磁盘上的文件夹是唯一的事实来源：没有副本，没有注册表，没有每个项目的激活。

快速入门

git clone https://github.com/FlowMCP/flowmcp-cli.git
cd flowmcp-cli
npm i
npx flowmcp init

然后将CLI指向架构文件夹，方法是将其添加到 ~/.flowmcp/config.json:

{
    "envPath": "~/.flowmcp/.env",
    "schemaFolders": [
        { "name": "development", "path": "~/path/to/flowmcp-schemas/schemas/v4.0.0" }
    ]
}

每个文件夹中的每个工具现在都是可调用的——不 add. path 可能是 ~-或锚相对。中缺少所需的API密钥的工具 .env 显示为 [disabled: missing KEY] 并跳过；所有其他工具保持可用。

命令

设置

工具发现（代理模式）

不 add/remove/reload/group：每个配置文件夹中的每个工具都可以立即用于 search/list/call。要添加或删除文件夹，请编辑 schemaFolders[] 在 ~/.flowmcp/config.json.

模式管理

不 import/import-registry/update：没有注册表或互联网同步。克隆架构存储库(gh repo clone …)并将路径添加到 schemaFolders[].

及时管理

验证和测试

评分

这 grading 命令运行生产分级系统（v2） 工作台岛。它们都可以通过以下方式访问 flowmcp grading ... 和 flowmcp dev grading ... （the dev 前缀是可选的）。

旗帜： --phase <area> 将评分限制在单一领域/技能； --target <grade> 添加优质镜头 plan/finalize （工作清单也 包括目标下的模式；从不降低质量标准）； --on-conflict <abort\|skip\|overwrite> 设置写入冲突策略 （默认：不覆盖）； --grading-data <path> 覆盖岛屿位置 一个电话。

岛屿位置

分级岛默认为 ~/.flowmcp/grading （与全球 ~/.flowmcp/.env 和 config.json --唯一的真理来源）。决心 顺序（全部显式，无静默回退）：

1. --grading-data <path> 标志（针对当前目录解析）
2. FLOWMCP_GRADING_DATA env-var（针对当前目录解析）
3. "gradingDataDir" 在 ~/.flowmcp/config.json （坚决反对 ~/.flowmcp)
4. 默认 ~/.flowmcp/grading

要设置持久自定义位置，请添加到 ~/.flowmcp/config.json:

{ "gradingDataDir": "grading" }

相对值根据 ~/.flowmcp；按原样使用绝对值。

舞台模型

评分分为三个阶段。CLI拥有第1和第3阶段；这个 利用 （你的Claude Code代理循环）拥有第二阶段。从实时读取架构源 schemaFolders[] 每次运行时，都没有单独的摄入/导入步骤 岛屿(index.json/prompts.json/state.json/等级快照）是建立在 第一轮。

流量自动检测

目标的路径决定了测试流程、层次和最大可达等级：

• providers/<target>/ → 供应商测试 --层级 autonomous，最大值 B级.
• selections/<target>/ → 选拔测试 --层级 group-bound, A级 可达成的。
• 存在于两者之下的目标 providers/ 和 selections/ 被拒绝 错误和修复提示；传递一个明确的路径来消除歧义。

移交给安全带

grading non-deterministic --emit-prompts 不进行非确定性评分 本身。它写道：

• prompts.json --每个区域有一个评分提示，每个提示都有一个目标块。
• state.json --跑步接力棒（哪些区域正在等待/完成），以原子方式更新 并且从未被覆盖。

然后，线束驱动非确定性回路： Agent() 运行每个 该区域的评分提示与球门不符。一个小的快速评估者（Haiku）读到 只有成绩单 --它不需要任何工具来决定何时实现目标。 为了实现这一点，循环将其进度显示在转录本中 [GRADING] 例如：

[GRADING] area=single-test/getFirstPrice schema-valid=ok status=graded written=ok
[GRADING] PROGRESS 7/12
[GRADING] DONE

达到目标后，将分数交还给CLI：

# Stage 1 — deterministic pretest + emit prompts (provider test)
flowmcp grading non-deterministic providers/defillama --emit-prompts

# Stage 2 — harness grades each area (outside the CLI), writing scores

# Stage 3 — consume the harness scores, rebuild the index, finalize
flowmcp grading non-deterministic providers/defillama --consume-scores scores.json

# Inspect the rollup, then export the graded state back to the source
flowmcp grading state providers/defillama
flowmcp grading export providers/defillama

代理管理

架构迁移

资源管理（SQLite）

缓存管理

执行

诊断

doctor 运行七次检查： config-single-source （每 schemaFolders[] 路径存在）， schema-load （每个模式模块加载）， shared-list-resolve （每项声明 sharedLists ref解析非空-- LST-001/HND-001/LST-006), module-present （每 requiredLibraries 实际条目 负载 --一个真实的 import/dlopen，不仅仅是 require.resolve --从允许的库、CLI库或模式目录；一个真正缺失的库是 LIB-001 使用可复制粘贴的安装命令，该命令使用 github:FlowMCP/<repo> 对于org内部附加组件，已安装但无法卸载的本机绑定是 LIB-BINDING 带有重建提示）， key-coverage (requiredServerParams 对 .env — INFO 只有；缺少密钥会禁用单个工具，它们不是结构性故障），以及 cli-version机器可读的结果是stdout上的JSON；人工摘要打印到stderr（被抑制） --json).

错误代码

CLI显示的每个捕获的故障都会携带 PREFIX-NNN 代码（3-4个大写字母、破折号、三位数字；例如。 LST-001, CFG-002, SQL-004).严重性为 ERROR （块）， WARNING，或 INFOA. 宣布 sharedLists 现在无法定位或解析的引用 大声失败 使用代码，而不是默默地返回空列表。 flowmcp doctor 读取这些代码。运行时代码命名空间已在中注册 规格寻路器 (09-validation-rules.md → CLI Runtime Error Codes)每个代码的权威所在地都是它的 try/catch 网站在 src/task/FlowMcpCli.mjs.

工具参考格式

source/file.mjs              # All tools from a schema
source/file.mjs::routeName   # Single tool from a schema

附加组件

概念

附加组件是特定于格式的适配器，当模式声明具有非平凡数据格式的资源时，FlowMCP CLI会按需加载这些适配器。它们封装了不属于模式定义的知识，例如特定SQLite数据库必须如何构建，可以从中派生出哪些自动工具，或者如何验证质量保证（印章）。

插件作为独立的GitHub存储库运行，而不是作为CLI的一部分。这将模式逻辑（正在查询什么？）与格式逻辑（格式是如何构造的？）分开，并允许两者独立发展。CLI通过加载插件 github: 一旦模式引用了它们，就可以根据需要进行简写。

承诺：指向插件的模式会自动在插件验证为符合规范且质量有保证的数据源上生成工具。模式作者不编写SQL代码，插件作者也不编写模式样板。

示例：sqlite-gtfs

第一个附加组件是 geo-gtfs-toolkit它将GTFS调度馈送（ZIP中的CSV）转换为符合规范的SQLite数据库，并提供基于功能的自动工具生成。模式引用它如下：

export const schema = {
    namespace: 'gtfsde',
    name: 'gtfsde-transit-v2',
    version: '2.0.0',
    main: {
        resources: [
            {
                source:      'sqlite-gtfs',
                mode:        'file-based',
                path:        '${FLOWMCP_RESOURCES}/gtfs-de.db',
                addon:       'geo-gtfs-toolkit',
                addonSource: 'github:FlowMCP/geo-gtfs-toolkit'
            }
        ]
    }
}

source: 'sqlite-gtfs' 向CLI发出需要附加组件的信号。 addon 命名包(geo-*-toolkit)，而 addonSource 指向GitHub克隆URL，其仓库保留自己的名称(*-sqlite-toolkit 对于三个sqlite存储库）--始终 github:<org>/<repo>，没有npm注册表。 ${FLOWMCP_RESOURCES} 是一个路径变量（请参阅下一节），解析为默认值 ~/.flowmcp/resources/.

发现：ADDON_RESTRY

CLI为每个已知注册表项保留一个注册表项 source 类型， 硬编码 在 src/data/addons.mjs 在V1中。每个条目有三个字段：

export const ADDON_REGISTRY = {
    'sqlite-gtfs': {
        name:           'geo-gtfs-toolkit',
        source:         'github:FlowMCP/geo-gtfs-toolkit',
        defaultVersion: 'main'
    }
}

name 是附加组件标识符（必须匹配 addon 在模式中）， source 是 github: 位置，以及 defaultVersion 当架构未设置 addonVersion在V1中，注册表是硬编码的；以后的版本可能会从外部源扩展它。

规格参考： flowmcp-spec/spec/v4.0.0/13-resources.md，“SQLite GTFS资源”一节。

相关章节： 路径变量 (${FLOWMCP_RESOURCES}), FlowMCP目录结构 （默认位置 ~/.flowmcp/resources/), 数据来源——用户责任 （数据库由用户创建）。

路径变量

路径变量允许用户配置，而无需为每个设置重写模式。它们通常出现在 path 模式资源的字段——例如，指向用户决定其位置的本地存储的SQLite数据库。

CLI解析以下变量：

解析分两步进行：首先检查是否设置了env-var；如果没有，则退回到记录在案的默认值。没有默认值的变量（例如 ${HOME})必须由操作系统提供，否则将适用错误情况。

错误 RES035

当CLI无法解析变量时，例如因为未知变量出现在 path，或者没有默认值的env-var为空——资源 call 中止与 RES035。用户通过显式设置env var来修复此问题(export FLOWMCP_RESOURCES=/path/to/dir)或者通过将数据库移动到默认位置。

这 FLOWMCP_* 姓名家族

路径变量跟在模式规范图元名称后面→ 变量名。 ${FLOWMCP_RESOURCES} 直接绑定到spec基元 main.resources 并确立 FLOWMCP_* 名字家族。未来的扩展是可以预见的，例如 ${FLOWMCP_LOGS} 用于日志目录或 ${FLOWMCP_CACHE} 作为显式缓存挂钩。仅在V1中 ${FLOWMCP_RESOURCES} 实施。

备选位置示例：

export FLOWMCP_RESOURCES=/Volumes/MyData/flowmcp
flowmcp call <tool-name>

相关章节： 附加组件 （模式示例 ${FLOWMCP_RESOURCES}), FlowMCP目录结构 （默认分辨率）。

数据来源——用户责任

FlowMCP分配 不 公共存储库中的提供者数据。有三个原因，它们同时适用。

许可证。 GTFS提要和可比较的提供商数据集均受其自己的许可条款的约束，从CC BY 4.0到自定义EULA再到提供商特定的条款。将数据放入公共存储库无意中将此合规义务转移到存储库及其所有分支上。FlowMCP通过将数据保留给用户来避免这种情况。

规模。 真正的供应商馈送达到40 MB及以上（DB Bahn FV时间表约为50 MB，区域VBB馈送更大）。Git历史中的此类数据量会使每个克隆都膨胀，并使存储库变得笨重。代码和数据属于不同的生命周期。

新鲜。 订阅源每天或每周更新一次。存储库状态总是过时的——用户必须定期检查存储库中捆绑的版本是否仍然与现实相符。用户直接从提供者那里提取和转换更为简洁。

用户工作流

从提供者提要到FlowMCP可用的数据库的路径有四个步骤：

1. 下载 来自提供商的GTFS馈送（示例： gtfs.de/de/feeds/、区域开放数据门户、提供商拥有的下载页面）
2. 转换 通过 geo-gtfs-toolkit 插件（有关确切的调用，请参阅插件README）
3. 商店 数据库位于 ${FLOWMCP_RESOURCES}/<name>.db （默认值 ~/.flowmcp/resources/<name>.db)
4. 使用 模式——它已经可以通过 call/list 一旦其文件夹位于 schemaFolders[] （无激活步骤）

具体命令示例：

# 1. Download the GTFS feed (example)
curl -O https://download.gtfs.de/germany/free/latest.zip

# 2. Convert via the add-on (see geo-gtfs-toolkit README)
cd ~/code/geo-gtfs-toolkit
node convert.mjs --input=~/Downloads/latest.zip --output=~/.flowmcp/resources/gtfs-de.db

# 3. Optional: move the database to a different location
#    (when ${FLOWMCP_RESOURCES} does not point at the default)

# 4. Call the tool directly (the schema's folder is in schemaFolders[])
flowmcp call <tool-name>

预推保护

附加存储库(geo-gtfs-toolkit)发送验证脚本 scripts/check-no-provider-data.sh 在每次提交或推送之前检测大型或特定于提供程序的文件，并中止推送。此策略也适用于用户分叉——贡献者应将脚本连接到他们自己的预推挂钩中。

任何为新提供者贡献模式的人都可以提供 只有模式和路径变量 --从来没有饲料本身。

相关章节： 路径变量 （步骤3使用 ${FLOWMCP_RESOURCES}), FlowMCP目录结构 （默认存储位置）， 附加组件 （步骤2需要附加组件）。

FlowMCP目录结构

FlowMCP使用中央用户目录 ~/.flowmcp/ 这在所有项目中保持一致。它将API键、缓存和用户资源保存在一个位置——每个项目可以覆盖单个值，而默认查找保持在中心位置。

~/.flowmcp/
├── .env             ← API Keys (Single Source of Truth)
├── cache/           ← Schema cache (CLI-managed)
└── resources/       ← User DBs (default for ${FLOWMCP_RESOURCES})

.env --单一真相来源

全球 ~/.flowmcp/.env 是所有FlowMCP工具的API密钥的唯一真相来源。由用户手动维护；CLI从不自动创建它，也从不覆盖它。项目本地覆盖可以放置在 projects/<name>/.flowmcp/.env --查找路径首先是项目本地路径，然后是全局路径。

resources/ --默认值为 ${FLOWMCP_RESOURCES}

目录 ~/.flowmcp/resources/ 是路径变量的默认分辨率 ${FLOWMCP_RESOURCES}用户可以将env-var设置到其他位置，例如外部驱动器或中央数据卷，然后CLI动态解析到该位置。

export FLOWMCP_RESOURCES=/Volumes/MyData/flowmcp

相关章节： 路径变量 （分辨率逻辑）， 数据来源——用户责任 （为什么数据库放在这里，而不是存储库中）。

全球旗帜

工作流示例

基本设置和使用

# 1. Setup
flowmcp init

# 2. Point the CLI at a schema folder (clone it yourself first):
#    gh repo clone FlowMCP/flowmcp-schemas ~/flowmcp-schemas
#    then add to ~/.flowmcp/config.json:
#      "schemaFolders": [ { "name": "development", "path": "~/flowmcp-schemas/schemas/v4.0.0" } ]

# 3. Discover tools (all immediately available — no add)
flowmcp search coingecko
flowmcp list

# 4. Use tools directly
flowmcp call list-tools
flowmcp call simple_price_coingecko '{"ids":"bitcoin","vs_currencies":"usd"}'

要通过MCP提供模式，请使用 mcp-agent-server — flowmcp run 已删除（见顶部注释）。

模式开发

# Structure-check a single schema file (offline, no API calls)
flowmcp schema-check ./my-schema.mjs

# Structure-check an entire directory
flowmcp schema-check ./schemas/my-provider/

# Deterministic validation (structural validate + data pretest) for one schema
flowmcp grading deterministic my-namespace/my-schema

# Restrict the pretest to one tool
flowmcp grading deterministic my-namespace/tool/getBalance

测试

注： flowmcp dev test (project / user / single)曾经是 移除. 它的PASS标准（仅限HTTP 200）是确定性的严格子集 分级预测试，还需要非空数据（HTTP 200 和 真实数据）。架构检查现在有 一 路径： grading.

flowmcp grading deterministic <id> 运行结构验证 加 这个 单个模式的确定性数据预测试(<namespace>/<schema>)或a 单一工具(<namespace>/tool/<name>).确实如此 不 发出提示并执行 不 运行非确定性LLM评分 --only 国旗上写着 曾经居住的v4原始视图 dev test:

过滤方式 --only

使用 --only=<csv> 将v4基元视图限制为选定的基元。 允许值： tools, resources, skills, prompts, selections （逗号分隔为多个）。

# Only the Resource primitive view
flowmcp grading deterministic my-namespace/my-schema --only=resources

# Resources and Skills only
flowmcp grading deterministic my-namespace/my-schema --only=resources,skills

结构化输出 --json

加 --json 以发出机器可读的结果。JSON对象包含 status, mode, target，the validate 块 pretest 块 (ok, passedDownloadable, required, results), hints和（with --only一 primitives 块。

flowmcp grading deterministic my-namespace/my-schema --json

技能的一次性LLM测试故意不是CLI功能；他们跑了进来 线束（见规范v4.0.0§10）。

架构迁移（v2到v3）

# Preview what would change
flowmcp migrate ./schemas/ --dry-run

# Migrate a single file
flowmcp migrate ./schemas/provider/schema.mjs

# Migrate all schemas in a directory
flowmcp migrate --all ./schemas/

代理导入

# Import an agent from the registry
flowmcp import-agent my-agent

# Validate a catalog directory
flowmcp validate-catalog ./my-catalog/

目录验证

这 validate-catalog 命令检查目录目录的结构是否正确：

• registry.json 必须存在并与目录名匹配
• 所有引用的架构文件必须存在
• 所有引用的共享文件必须存在
• 所有代理清单文件必须存在
• 架构规范版本必须有效（2.0.0或3.0.0）

flowmcp validate-catalog ./catalogs/my-catalog/

{
    "status": true,
    "catalog": "my-catalog",
    "schemaSpec": "3.0.0",
    "counts": {
        "shared": 2,
        "schemas": 15,
        "agents": 1
    },
    "errors": [],
    "warnings": []
}

资源管理

对于具有基于SQLite的资源的模式：

# Create databases defined in a schema
flowmcp resource create ./schemas/provider/schema.mjs -y

# Preview database path migrations
flowmcp resource migrate --dry-run

# Execute migrations
flowmcp resource migrate -y

缓存管理

# Check cache size and entries
flowmcp cache status

# Clear everything
flowmcp cache clear

# Clear a specific namespace
flowmcp cache clear etherscan

及时管理

# List all prompts
flowmcp prompt list

# Search for prompts
flowmcp prompt search "blockchain"

# View a specific prompt
flowmcp prompt show analysis/token-report

# Add a prompt from a markdown file
flowmcp prompt add analysis token-report --file ./prompts/token-report.md

# Remove a prompt
flowmcp prompt remove analysis token-report

文档

完整文档请访问 flowmcp.github。io。请参阅 CLI参考 获取详细的命令文档。

许可和服务条款

FlowMCP命令行界面 麻省理工学院许可MIT许可证涵盖了此存储库中的CLI工具（开发、验证、分级、部署、环境助手）。

通过CLI访问的模式 调用第三方API，每个API都有自己的服务条款。模式可能包括一个可选的 meta.termsOfService 字段中包含提供者的ToS URL和上次验证的日期。 我们不对这些服务条款进行分类或解释。 用户应全权负责在使用前审查每个API提供商的条款。

FlowMCP对ToS合规性、数据许可或适用于任何目的不作任何陈述。看 免责声明.md 了解详情。

许可证

麻省理工学院