FlowMCP

FlowMCP Core

Version: 4.0.0

既存の Web API を標準化された Model Context Protocol（MCP）インターフェースに適合させるための包括的なフレームワークです。AI システムが構造化され、テスト可能で、意味的に一貫性のある方法でアクセスできるようにします。FlowMCP Core は、組み込みの検証、テスト、エラー処理を備え、あらゆる REST API を MCP 対応ツールに変換します。

機能

• v4 パイプライン：セキュリティスキャン、レガシーアダプター、バリデーター、ライブラリローダー、セレクション、ハンドラー、スキル、プレースホルダー解決、リソース DB、プロンプトを含む、16 ステップのオーケストレーションされた読み込み
• セレクション（第 5 のプリミティブ）：SelectionLoader と SelectionValidator による、オペレーターが厳選したツールサブセットを第一級の機能として提供
• グレードレポート：GradeReporter による A～F のスキーマ品質の自動評価（評価プロンプト＋決定論的スコアリング）
• プレースホルダー解決：型付きカタログ（ツール、リソース、プロンプト、スキル、sharedLists、inputs、prefill）に基づいて 12 種類のプレースホルダーを解決
• キャプチャフロー：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/legacy ツリーは削除されました。ルートエクスポートとすべてのモジュールは 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 Public 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 スキーマに対して skills: {} が返されます。

v4 スキーマ構造

v4 スキーマでは、version: '4.0.0' を指定した export const main と、（任意で）ファクトリーとしての 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 のみのスキーマでは空にできます）

各ツールに必須の meta フィールド

フィールド	型	備考
isReadOnly	boolean	GET／読み取り専用アクセスの場合は true
isConcurrencySafe	boolean	デフォルトは isReadOnly
isDestructive	boolean	デフォルトは !isReadOnly
searchHint	string	ツール検索用の簡潔なヒント
aliases	string[]	ツールの別名
alwaysLoad	boolean	フィルタリングされている場合も強制的に読み込みます

ヒューリスティックを使って初期 meta ブロックを生成するには、MetaGenerator.generateForSchema({ tools }) を使用してください。

v4 スキーマの例

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 マップには 2 つのエントリーのみが含まれます。.（FlowMCP ファサードを含む v4 の公開 API）と ./v4（1 リリースだけ維持され、その後削除されるエイリアス）です。./v1、./v2、./legacy のサブパスは存在しなくなりました。
• .activateServerTools、.filterArrayOfSchemas、.getArgvParameters、.prepareActivations などの v1/v2 メソッドは、公開 API から削除されました。代わりに 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 は削除されました。 未使用の @modelcontextprotocol/sdk 依存関係は flowmcp-core から削除されました。Core は FlowMCP.loadSchema() と FlowMCP.prepareServerTool() を介してプロセス内で MCP ツールを構築します（ツールの準備に SDK は不要です。利用側が独自の McpServer に接続します）。すぐに使える MCP サーバーには、mcp-agent-server を使用してください。

エラー処理

v4 パイプラインはすべてのエラーと警告を結果オブジェクトに収集し、検証に失敗しても例外をスローしません。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（スキーマの構造、メタブロック、バージョン）
3. SEL* — SelectionLoader / SelectionValidator
4. SKILL* — SkillLoader / SkillValidator（ツール参照の欠落を含む）
5. PIPE-WARN / PIPE-INFO — 致命的ではないパイプライン通知

テストと検証

リポジトリのルートから v4 テストスイートを実行します。

npm test
npm run test:coverage:src

スキーマの作成者は、各ツールに少なくとも 1 つの _description エントリーを含む tests 配列を設定してください。v4 パイプラインではテスト定義は main.tools[name].tests に保持され、検証中に削除されることはありません。

パフォーマンスと最適化

• パイプラインは非同期で、可能な場合は独立したステップ（選択、プリフィル、ライブラリの読み込み）を並行して実行します。
• SecurityScanner と SchemaLoader は静的解析と動的インポートを使用し、eval やプロセスの起動は行いません。
• ヒューリスティックヘルパー（MetaGenerator.generateForSchema、OutputSchemaGenerator.generateFromResponse）は、ツールごと／レスポンスごとにキャッシュして再計算を避けます。
• Skills のみを扱う特別なパスではパイプラインを短絡し、ブラウザー自動化スキーマの読み込み時間を最小限に抑えます。

ドキュメント

その他のドキュメントと例については、以下を参照してください。

• FlowMCP Specification v4.0.0 — 完全な仕様（現行）
• MIGRATION.md — v1 → v2 の過去のアップグレードガイド（4.0.0 で両方のツリーは削除されましたが、参考用に保持されています）。flowmcp migrate を使ってスキーマファイルを v4 に移行してください。
• tests/unit/v4/ — v4 パイプラインとモジュールのリファレンステストスイート

ライセンスと利用規約

FlowMCP Core は MIT ライセンスです。MIT ライセンスは、このリポジトリ内のスキーマ検証、エージェントマニフェストの読み込み、ツール実行のコードを対象とします。

FlowMCP 経由で読み込まれるスキーマは、それぞれ独自の利用規約を定めているサードパーティの API にアクセスします。スキーマには、プロバイダーの利用規約 URL と、リンクを最後に確認した日付を記載する任意の meta.termsOfService フィールドを含めることができます。**これらの利用規約を分類または解釈することはありません。**各 API プロバイダーの規約を使用前に確認する責任は、ユーザーのみが負います。

FlowMCP は、利用規約への準拠、データのライセンス、またはいかなる目的への適合性についても、表明を行いません。詳しくは DISCLAIMER.md をご覧ください。

ライセンス

MIT