FlowMCP

FlowMCP Core

版本： 4.0.0

一个全面的框架，可将现有 Web API 适配为标准化的 Model Context Protocol（MCP）接口，为 AI 系统提供结构化、可测试且语义一致的访问方式。FlowMCP Core 可将任意 REST API 转换为兼容 MCP 的工具，并内置验证、测试和错误处理功能。

功能

• v4 管道：通过 16 个步骤的编排式加载流程，完成安全扫描、旧版适配器、验证器、库加载器、选择项、处理程序、技能、占位符解析、资源数据库和提示词的加载
• 选择项（第 5 种基本元素）：通过 SelectionLoader 和 SelectionValidator，将由操作人员整理的工具子集作为一等功能
• 等级报告：通过 GradeReporter 自动进行 A–F 级架构质量评级（评估提示词 + 确定性评分）
• 占位符解析：根据类型化目录解析 12 种占位符类型（工具、资源、提示词、技能、sharedLists、inputs、prefill）
• 捕获流程：通过 OutputSchemaGenerator 实时捕获响应，并根据真实 API 响应自动推导输出架构
• 一次性技能：SkillContentGenerator 根据架构 + sharedLists 生成独立的技能内容
• 每个工具的元数据块：每个 v4 工具都声明 isReadOnly、isConcurrencySafe、isDestructive、searchHint、aliases、alwaysLoad——通过 MetaGenerator 生成和验证
• 仅技能的特殊路径：验证后识别 tools: {} 的架构，并快速跳过管道步骤（跳过步骤 7–9、11–15）
• 库加载：通过 LibraryLoader 注入允许列表中的运行时库（使用 mergeAllowlist）
• 资源数据库管理器：通过 ResourceDatabaseManager 初始化基于 SQLite 的资源
• 安全扫描器：在加载任何模块之前，静态扫描禁止模式（eval、imports）
• 仅 v4（4.0.0）：v1/v2/旧版目录树已移除——根导出和每个模块均为 v4。请参阅重大变更：仅 v4（4.0.0）

目录

• FlowMCP Core
  • 功能
  • 目录
  • 快速开始（v4）
  • v4 公共 API
  • v4 架构结构
  • 重大变更：仅 v4（4.0.0）
  • 错误处理
  • 测试与验证
  • 性能与优化
  • 文档

快速开始（v4）

import * as v4 from 'flowmcp-core/v4'

const { Pipeline } = v4

// v4 Pipeline — loads, validates, and returns a result object
const result = await Pipeline
    .load( {
        filePath: './schemas/etherscan-io/etherscan.mjs',
        listsDir: './schemas/shared/lists',
        allowlist: null,
        selectionFiles: [],
        prefillTimeout: 1000,
        fetchFn: null,
        userParams: {}
    } )

if( !result.status ) {
    console.error( 'Pipeline failed:', result.messages )
    return
}

// Result object contains all primitives:
//   main, handlerMap, resourceHandlerMap, sharedLists, libraries,
//   skills, selections, prompts, contentMap, prefillResults, warnings
console.log( 'Tools available:', Object.keys( result.main.tools ) )
console.log( 'Skills loaded:', Object.keys( result.skills ) )
console.log( 'Warnings:', result.warnings )

等级报告

import * as v4 from 'flowmcp-core/v4'

const { GradeReporter } = v4

const { prompts } = GradeReporter
    .buildEvalPrompts( { schema: result.main, skill: null } )

const { grade, scoreSummary } = GradeReporter
    .grade( {
        schemaId: 'etherscan/4.0.0',
        deterministicResult: { passed: true },
        scores: { coverage: 90, accuracy: 85, clarity: 80 },
        validatorVersion: '4.0.0'
    } )

console.log( 'Grade:', grade )         // 'A' | 'B' | 'C' | 'D' | 'F'
console.log( 'Summary:', scoreSummary )

v4 公共 API

v4 API 通过 flowmcp-core/v4 导出。每个模块都是专注的静态类，公共接口较小（每个模块有 1–3 个方法）。内部辅助函数保持私有。

模块	公共方法
Pipeline	load({ filePath, listsDir, allowlist, selectionFiles, prefillTimeout, fetchFn, userParams })
MainValidator	validate({ main })
SelectionLoader	load({ filePath })
SelectionValidator	validate({ selection })
PlaceholderResolver	resolve({ content, catalog, sharedLists, inputs, prefillResults })
PrefillExecutor	execute({ skill, userParams, fetchFn, timeout })
MetaGenerator	generate({ tool })，generateForSchema({ tools })
GradeReporter	buildEvalPrompts({ schema, skill })，grade({ schemaId, deterministicResult, scores, validatorVersion })
OutputSchemaGenerator	generateFromResponse({ response, mimeType, schemaId })
SkillContentGenerator	generate({ schemas, sharedLists })
SkillValidator	validate({ skills, tools, resources })
AgentManifestValidator	validate({ manifest })
IdResolver	resolve({ reference, catalog })
LibraryLoader	load({ requiredLibraries, allowlist })，getDefaultAllowlist()，mergeAllowlist({ extraAllowlist })
ResourceDatabaseManager	initialize({ resources, schemaRef, schemaDir })

Pipeline.load() 返回结构

{
    status: true,                // Boolean — overall success
    messages: [],                // Error messages when status === false
    main,                        // The validated v4 `main` object
    handlerMap: {},              // Per-tool handler functions
    resourceHandlerMap: {},      // Per-resource handler functions
    sharedLists: {},             // Resolved shared lists
    libraries: {},               // Loaded libraries (allowlist-filtered)
    skills: {},                  // Skills with resolved content
    selections: {},              // Loaded selection files
    prompts: {},                 // Loaded prompts
    contentMap: null,            // Map produced by SkillContentGenerator
    prefillResults: null,        // Map produced by PrefillExecutor
    warnings: []                 // Non-fatal warnings
}

仅包含 Skills 的特殊路径

当 Object.keys( main.tools ).length === 0 时，流水线会在步骤 6 之后采用特殊路径：跳过 HandlerFactory、SelectionLoader、PrefillExecutor、PlaceholderResolver、ResourceValidator 和 PromptLoader。handlerMap 和 resourceHandlerMap 返回 {}。注意：v4 中禁止使用 main.skills——请改用顶层 skills 导出。因此，对于 v4 schema，此特殊路径会返回 skills: {}。

v4 Schema 结构

v4 schema 声明 export const main，其中包含 version: '4.0.0'，并可选择将 export const handlers 声明为工厂。tools 下的每个条目都必须包含完整的 meta 块。

必填字段

键	类型	描述
namespace	string	唯一命名空间，正则表达式为 ^[a-z][a-z0-9-]*$
name	string	面向用户的名称
description	string	API 简要说明
version	string	必须等于 '4.0.0'
root	string	API 的基础 URL
tools	object	工具定义映射（仅包含 Skills 的 schema 可以为空）

每个工具必需的 meta 字段

字段	类型	说明
isReadOnly	boolean	GET / 只读访问时为 true
isConcurrencySafe	boolean	默认值为 isReadOnly
isDestructive	boolean	默认值为 !isReadOnly
searchHint	string	工具搜索提示
aliases	string[]	工具的其他名称
alwaysLoad	boolean	即使经过筛选也强制加载

使用 MetaGenerator.generateForSchema({ tools })，通过启发式方法生成初始 meta 块。

v4 Schema 示例

export const main = {
    namespace: 'etherscan',
    name: 'Etherscan',
    description: 'Etherscan REST API.',
    version: '4.0.0',
    docs: [ 'https://docs.etherscan.io' ],
    tags: [ 'evm', 'blockchain' ],
    root: 'https://api.etherscan.io',
    requiredServerParams: [ 'API_KEY' ],
    tools: {
        getBalance: {
            method: 'GET',
            path: '/api?module=account&action=balance',
            description: 'Return the balance for an address.',
            parameters: [],
            meta: {
                isReadOnly: true,
                isConcurrencySafe: true,
                isDestructive: false,
                searchHint: 'fetch ETH balance for an address',
                aliases: [],
                alwaysLoad: false
            },
            tests: [
                { _description: 'happy path' }
            ]
        }
    }
}

export const handlers = ( { sharedLists, libraries } ) => ( {
    getBalance: {
        postRequest: async ( { response } ) => {
            return { response: { balance: response[ 'result' ] } }
        }
    }
} )

// Skills, resources, and prompts are top-level exports — never nested in main
export const skills = {
    'lookup-balance': {
        version: 'flowmcp/4.0.0',
        type: 'namespace',
        whenToUse: 'When the user wants to lookup an ETH balance.',
        content: 'Use {{tool:etherscan/getBalance}} with the parameter address.'
    }
}

重大变更：仅支持 v4（4.0.0）

4.0.0 移除了 v1、v2 和 legacy 目录树。 此软件包现在仅支持 v4：

• exports 映射仅包含两个条目——.（v4 接口，包括 FlowMCP 门面）和 ./v4（仅保留一个版本的别名，之后将移除）。./v1、./v2 和 ./legacy 子路径不再存在。
• .activateServerTools、.filterArrayOfSchemas、.getArgvParameters 和 .prepareActivations 等 v1/v2 方法已从公共接口中移除。请改用 FlowMCP.loadSchema() + FlowMCP.prepareServerTool() 构建 MCP 服务（参见快速入门和服务集成指南）。
• 按 SHA 固定版本的安装仍可正常使用。 按提交哈希固定版本的使用者（github:FlowMCP/flowmcp-core#<sha>）不受影响——旧提交仍可在 Git 历史记录中访问。只有更新固定版本、文档读者或未固定版本的安装才会受到影响。更新固定版本时必须迁移到 v4 API。
• 使用显式的 flowmcp migrate 转换器将 v1/v2/v3 架构文件转换为 v4。v1 中逐方法的参考文档仍保留在 Git 历史记录中。

完整的 4.0.0 重大变更公告请参阅 CHANGELOG。

已移除 MCP SDK。 flowmcp-core 已舍弃未使用的 @modelcontextprotocol/sdk 依赖项。Core 会通过 FlowMCP.loadSchema() + FlowMCP.prepareServerTool() 在进程内构建 MCP 工具（准备工具无需 SDK——使用者会将这些工具接入自己的 McpServer）。如需开箱即用的 MCP 服务，请使用 mcp-agent-server。

错误处理

v4 Pipeline 会在结果对象中收集所有错误和警告——验证失败时绝不会抛出异常。请检查 status、messages 和 warnings 并作出相应处理。

const result = await Pipeline.load( { filePath: './schemas/etherscan.mjs' } )

if( !result.status ) {
    result.messages
        .forEach( ( msg ) => { console.error( '- ' + msg ) } )
    return
}

result.warnings
    .forEach( ( w ) => { console.warn( '! ' + w ) } )

错误类别

1. SEC* — SecurityScanner 发现的问题（禁止的模式、导入、eval）
2. VAL* — MainValidator（架构形状、meta-block、版本）
3. SEL* — SelectionLoader / SelectionValidator
4. SKILL* — SkillLoader / SkillValidator（包括缺失的工具引用）
5. PIPE-WARN / PIPE-INFO — 非致命的 Pipeline 提示

测试与验证

在仓库根目录运行 v4 测试套件：

npm test
npm run test:coverage:src

架构作者应为每个工具配置一个 tests 数组，其中至少包含一个 _description 条目。v4 Pipeline 会将测试定义保留在 main.tools[name].tests 中——验证期间不会将其移除。

性能与优化

• Pipeline 为异步流程，并会在可能的情况下并发运行相互独立的步骤（selections、prefill、library loading）。
• SecurityScanner 和 SchemaLoader 使用静态分析和动态导入——不使用 eval，也不会启动子进程。
• 启发式辅助工具（MetaGenerator.generateForSchema、OutputSchemaGenerator.generateFromResponse）会按工具 / 响应缓存，避免重复计算。
• 仅 Skills 的特殊路径会提前结束 Pipeline，从而将浏览器自动化架构的加载时间降至最低。

文档

更多文档和示例：

• FlowMCP Specification v4.0.0 — 完整规范（当前版本）
• MIGRATION.md — 历史 v1 → v2 升级指南（两个目录树均已在 4.0.0 中移除；此文档仅供参考）。使用 flowmcp migrate 将架构文件迁移到 v4。
• tests/unit/v4/ — v4 Pipeline 和模块的参考测试套件

许可证和服务条款

FlowMCP Core 采用 MIT 许可。MIT 许可证适用于本仓库中的架构验证、Agent 清单加载和工具执行代码。

通过 FlowMCP 加载的架构会访问第三方 API，每个 API 都有各自的服务条款。架构可以包含可选的 meta.termsOfService 字段，其中包括服务提供商的服务条款 URL 以及我们上次验证该链接的日期。我们不会对这些服务条款进行分类或解读。 用户有责任在使用前自行查阅各 API 服务提供商的条款。

FlowMCP 不对服务条款合规性、数据许可或适用性作任何声明。详情请参阅 DISCLAIMER.md。

许可证

MIT