AKBridge

インストール | クライアント設定 | 呼び出し例

AKBridge 0.2.0 の破壊的変更：デフォルトのツール構成が all から router に変更されました。デフォルトモードに依存していたクライアントは、--mode all を明示的に指定する必要があります。同バージョンでは structured content、MCP Prompts、必要に応じたドキュメントリソース、Streamable HTTP に対応しています。旧版 SSE も引き続き利用できますが、deprecated としてマークされています。

AKShare の公開インターフェースを MCP ツールとして自動公開し、ルーティング検索、構造化出力、インターフェースごとの検証、自動検証とメンテナンスを提供します。現在の AKShare 基準バージョン、インターフェース数、検証結果については、中国語の検証概要と英語の検証概要をご覧ください。

AKBridge を選ぶ理由

AKShare は幅広い金融データインターフェースを網羅していますが、AI アシスタントに直接接続するには、Python の呼び出し、関数の選択、パラメーターの構築、DataFrame の変換、バージョン変更への対応が必要です。AKBridge はこれらの作業を、インストール、検索、検証が可能な MCP サービスにまとめています。金融リサーチアシスタント、マーケット分析エージェント、データ検索ツールの構築に適しています。

• AKShare の公開インターフェース全体を網羅し、少数のツールを長期にわたって手動でメンテナンスする必要がありません。
• 安定した3つのルーティングツールのみを LLM に公開し、数千のインターフェースによるコンテキストの負荷を軽減します。
• さまざまな形式の Python 戻り値を直接扱う代わりに、統一された JSON 出力、ページネーション、概要、エラー分類を提供します。
• AKShare の更新後にインターフェースの変更を自動検出し、インターフェースごとの検証で引き続き安全に使用できるか判断します。

AKBridge は AKShare に取って代わるものではありません。AKShare がデータを取得し、AKBridge がその機能を MCP クライアント、エージェント、その他のツールに確実に提供します。サードパーティのデータソース自体に起因するログイン、CAPTCHA、スクレイピング対策、レート制限、ネットワーク制約は引き続き存在し、それぞれ個別に報告されます。

検証状況

ステータス画像は検証レポートコマンドによって自動生成されます。詳細な結果は、中国語の検証概要、英語の検証概要、インターフェースごとの詳細をご覧ください。

GitHub Actions と Dependabot が AKShare と mcp の更新を自動で確認します。AKShare の同じメジャーバージョン内のアップグレードと、mcp の同じメジャーバージョン内のパッチアップグレードは、完全な検証に合格すると自動的にマージされます。また、依存関係の固定バージョンが変更されると、新しいバージョンが自動的にリリースされます。実行頻度、ゲート、リポジトリ設定については、自動検証とメンテナンスの説明をご覧ください。

機能

• AKShare の公開呼び出し可能インターフェースを自動検出し、関数シグネチャから MCP 入力スキーマを生成するため、数千のアダプターを手動でメンテナンスする必要がありません。
• DataFrame、Series、日付、一般的な NumPy スカラーの JSON 変換と、DataFrame の JSON 入力および時間インデックスの変換に対応しています。
• インターフェースごとの分離検証、タイムアウト制御、並行実行、検証パラメーターセット、中断地点からの再開を提供します。
• インターフェースごとの CSV 詳細と、JSON および Markdown の概要レポートを生成します。
• ローカルのセマンティックカタログ、決定論的な検索、3つのツールによるルーティングモードを提供します。
• raw、compact、summary の3つの出力モード、ページネーション、フィールドの型と単位のヒントに対応しています。
• リトライ、レート制限、キャッシュ、サーキットブレーカー、プロキシ設定、機密情報のマスキング、自動検証とメンテナンスのゲートを提供します。

インストール

コマンドラインツールのインストールには uv の使用をおすすめします。AKBridge 用に隔離された Python 3.11 以降の環境が管理されます。一般ユーザーは PyPI から最新リリース版をインストールします。

uv tool install akbridge
uv tool update-shell

ターミナルを再度開いて、次のコマンドで確認します。

akbridge --help
akbridge --mode router

2つ目のコマンドは stdio MCP サービスを起動し、クライアントからの接続を待ち受けます。ターミナルに何も表示されないのは正常です。Ctrl+C を押すと停止できます。デフォルトブランチの開発版をインストールするには uv tool install --force "git+https://github.com/kevynf/akshare-mcp-bridge.git" を使用します。アップグレードとアンインストールには、それぞれ uv tool upgrade akbridge と uv tool uninstall akbridge を使用します。

開発に参加する場合やコードを変更する場合にのみ、リポジトリをクローンしてください。

git clone https://github.com/kevynf/akshare-mcp-bridge.git
cd akbridge
uv sync --group dev
uv run --no-sync akbridge --mode router

stdio サービスの起動後、Web ページ、メニュー、コマンドプロンプトは表示されません。MCP クライアントは標準入出力を介してこのプロセスと通信します。

两种工具模式

router 是默认模式（自 0.2.0 起），只公布三个稳定工具，是连接 LLM 的推荐方式。all 模式保留所有已发现的 AKShare 原始函数工具，适合兼容已有客户端、逐接口验收和人工精确调用，但超过 50 个接口时会在 stderr 给出提示。hybrid 模式同时暴露两套接口，主要用于迁移与调试。

工具	用途
akbridge_search	在本地语义目录中检索接口、别名、类别和用途，返回小型 RAG 上下文。
akbridge_describe	返回一个接口的签名、参数、示例、返回类型、数据源链接和副作用标记。
akbridge_call	解析规范名称或唯一别名，调用接口，并选择输出模式和分页。

akbridge              # 默认即 router 模式
akbridge --mode all   # 显式选择完整工具面

检索器从 AKShare 公开函数自动生成 一级分类 → 源码模块 → 接口 路由树，例如 stock → stock_feature.stock_hist_em → stock_zh_a_hist。函数名、签名、别名和 docstring 构成默认的确定性词法证据，不调用 LLM、嵌入服务或远程向量数据库。MCP 资源 akbridge://skill 提供同一套运行时调用规程，它随服务暴露，不会自动安装成客户端 Skill。

自 0.2.0 起，三个 router 工具都声明了 outputSchema，并以 structuredContent 形式返回结构化结果，便于 MCP 客户端零成本消费；同时保留 TextContent JSON 文本作为向后兼容的回退。工具描述头部带有人类可读的 title（"AKBridge Search" 等）和 _meta.documentation_uri 指向 README。

AKShare 文档词法路由

正式发布的 wheel 和 sdist 会在 GitHub Actions 中，根据固定的 AKShare 版本解析对应的 release-vX.Y.Z 标签和 commit SHA，自动构建并包含文档索引；router 模式默认加载包内索引，服务搜索期间不会联网。文档块只关联 AKShare 顶层公开函数，补充自然语言术语和排序证据，不决定领域或模块结构；搜索结果会返回命中的文档标题和来源链接。

自 0.2.0 起，AKBridge 通过 MCP ResourceTemplate 发布文档资源模板；akbridge_search 命中时，documentation 数组会附带具体的 uri，客户端可用 resources/read 读取完整文档，无需访问外部 URL。没有加载文档索引时，模板仍可见，但搜索结果不会返回具体文档 URI。

源码开发时可手动重建或覆盖索引：

akbridge-docs build --ref <akshare-commit-sha> --output artifacts\akshare-docs.json
akbridge --mode router --document-index artifacts\akshare-docs.json

客户端配置

选择使用的 MCP 客户端，跳转到对应配置：Cherry Studio、Codex或其他客户端。

Cherry Studio

Cherry Studio 可以通过 stdio 直接启动 AKBridge，不需要额外的适配服务，推荐使用 router 模式。

协议安装：将下面的地址复制到浏览器地址栏或 Windows“运行”窗口，打开 Cherry Studio 后检查安装预览并确认。如果没有打开自定义协议，请改用下方的 JSON 导入。

cherrystudio://mcp/install?servers=eyJtY3BTZXJ2ZXJzIjp7ImFrYnJpZGdlIjp7InR5cGUiOiJzdGRpbyIsImNvbW1hbmQiOiJ1dngiLCJhcmdzIjpbImFrYnJpZGdlIiwiLS1tb2RlIiwicm91dGVyIl19fX0%3D

Cherry Studio 会以未启用、未信任状态导入配置，仍需由用户确认并启用。

从 JSON 导入：打开 设置 → MCP → MCP 服务器 → 添加 → 从 JSON 导入，粘贴：

{
  "mcpServers": {
    "akbridge": {
      "type": "stdio",
      "command": "uvx",
      "args": ["akbridge", "--mode", "router"]
    }
  }
}

启用服务并确认状态正常后，将 AKBridge 绑定到需要使用它的 Agent。首次启动时 uvx 可能需要下载并创建运行环境，会比后续启动更慢。

Codex 配置

在 Codex MCP 配置中加入：

[mcp_servers.akbridge]
command = "akbridge"
args = ["--mode", "router"]
startup_timeout_sec = 30
tool_timeout_sec = 120

保存配置并重启 Codex，客户端初始化成功后即可看到 AKShare 工具。

其他 MCP 客户端

支持 JSON MCP 配置的客户端（Claude Desktop 及兼容客户端）可以使用：

{
  "mcpServers": {
    "akbridge": {
      "command": "akbridge",
      "args": ["--mode", "router"]
    }
  }
}

调用示例

连接 MCP 服务后，用户可以直接描述数据需求，无需预先知道 AKShare 函数名：

查询股票代码 000001 从 2026-01-01 到 2026-08-06 的前复权日线行情。

类似的自然语言请求还有“获取 A 股实时行情”“查询中国 CPI 数据”“获取开放式基金净值”“查询国内期货实时行情”。MCP 客户端中的 LLM 负责把需求转换为下方的检索、描述和结构化调用；AKBridge 本身不使用 LLM，每个工具的参数来自对应 AKShare 函数签名，具体含义以工具描述和 AKShare 文档为准。

路由调用与结果格式

典型顺序是先检索、再描述、最后调用：

{"query": "A股历史行情", "limit": 5}
{"name": "stock_zh_a_hist"}

{
  "name": "stock_zh_a_hist",
  "arguments": {
    "symbol": "000001",
    "period": "daily",
    "start_date": "20260101",
    "end_date": "20260806",
    "adjust": "qfq"
  },
  "output_mode": "compact",
  "page": 1,
  "page_size": 100
}

输出模式	适用场景	返回内容
raw	兼容已有直接工具调用	原始 JSON 结构，默认最多 5,000 行。
compact	常规分析	行数据、分页信息、字段类型和按列名推断的单位提示。
summary	先判断数据是否适用	行数、列、空值统计、数值摘要和少量预览，不返回完整大表。

字段和单位提示由结果列名和 dtype 自动推断，属于辅助元数据，不替代 AKShare 或数据源的正式定义。

指标与可观测性

akbridge_call 默认 不 在响应里附带 metrics 快照，避免 by_api 累积表让每次响应变大。需要时显式传 include_metrics: true，或读取 akbridge://metrics 资源拿到全量计数器：

{"name": "stock_zh_a_hist", "arguments": {...}, "include_metrics": true}

akbridge_call 的 annotation 标记为 open-world 和 state-changing；客户端是否展示这些 annotation 取决于客户端实现。副作用接口的授权门禁还会由服务端强制执行。

结构化错误响应

所有工具错误都以 isError=true 返回，错误正文是 JSON 文档，包含稳定的 error.code 以及 LLM 恢复建议：

{
  "error": {
    "code": "UNKNOWN_API",
    "message": "Unknown AKShare API: foo",
    "suggestions": ["stock_zh_a_hist", "..."],
    "retry_hint": "Use akbridge_search to find candidates, then akbridge_describe to confirm the canonical name and schema."
  }
}

错误码枚举：UNKNOWN_API、TOOL_NOT_AVAILABLE、SCHEMA_VIOLATION、INVALID_ARGUMENT、UPSTREAM_TIMEOUT、UPSTREAM_ERROR、CIRCUIT_OPEN、RATE_LIMITED、SIDE_EFFECT_DENIED、UNKNOWN_RESOURCE、UNKNOWN_PROMPT、INTERNAL_ERROR。LLM 客户端可以基于 code 选择检索备用接口、放慢调用频率或放弃。

副作用接口

以 set_*、login、logout、configure 开头或名字含 token/secret/password/api_key/cookie 的接口被标记为副作用接口。无论客户端是否处理 annotations，AKBridge 都会在服务端拒绝缺少 allow_side_effect=true 的调用；这个参数仅表示上层已完成授权确认，AKBridge 不会自行显示确认框：

• ToolAnnotations.readOnlyHint=false、destructiveHint=true、idempotentHint=false
• 工具描述头部加 ⚠️ SIDE EFFECT: 警告前缀
• _meta.x-requires-confirmation=true，为支持该约定的 MCP 客户端提供授权提示
• 不参与缓存和自动重试

MCP Prompts

自 0.2.0 起，AKBridge 暴露三个协议层 MCP prompts，对应常见工作流：

Prompt	用途	必填参数
akbridge.query_financial_data	端到端 search → describe → call 引导	question
akbridge.describe_api	查看接口 schema、参数、示例	name
akbridge.search_catalog	检索接口目录	query

支持 MCP Prompts 的客户端可以从 Prompt 菜单选择对应流程；具体触发 UI 由客户端决定。

DataFrame 入参

少数计算接口需要 pandas.DataFrame，MCP 客户端可以传入记录数组：

{
  "data": {
    "index_column": "date",
    "rows": [
      {"date": "2026-01-05T09:30:00", "Open": 10.0, "High": 10.3, "Low": 9.9, "Close": 10.2}
    ]
  }
}

index_column 指定转换为 DataFrame 索引的列，ISO 日期字符串会自动转换为 DatetimeIndex。

インターフェースごとの受け入れ検証

インターフェース一覧は検出メカニズムによって自動生成され、AKShare のバージョン、インターフェース総数、関数シグネチャ、入力 Schema のハッシュ、自動生成された表示名、カテゴリ、別名、用途、例、戻り値のメタデータ、副作用のフラグ、データソースへのリンクを記録し、artifacts/acceptance/manifest.json に保存されます。artifacts/catalog.json は、同じディレクトリにあるコンパクトな RAG エクスポートです。よく使うコマンド：

.venv\Scripts\python.exe -m akbridge.acceptance manifest
.venv\Scripts\python.exe -m akbridge.acceptance run --limit 20 --timeout 30 --workers 4
.venv\Scripts\python.exe -m akbridge.acceptance run --resume --retry-status timeout --timeout 60

--limit は今回の受け入れ検証件数を制御し、--resume は前回の進捗から再開し、--retry-status timeout はタイムアウトしたインターフェースを再検証し、--name は指定したインターフェースのみを検証します。必須の受け入れ検証パラメーターは artifacts/acceptance/fixtures.json にあります。全パラメーターとチェックポイントからの再開の詳細は、自動受け入れ検証とメンテナンスの説明を参照してください。

受け入れ検証ステータス

ステータス	意味
passed	インターフェースが空でない結果を正常に返しました
passed_empty	インターフェースは正常に実行されましたが、現在の戻り値は空または戻り値がありません
failed	AKShare または上流データソースが実行エラーを返しました
timeout	インターフェースが指定時間内に完了しませんでした
fixture_required	必須の受け入れ検証パラメーターがありません
worker_failed	MCP アダプターまたは分離実行プロセスでエラーが発生しました
adapter_passed	検出、Schema、アダプター契約のみを検証しました。サードパーティのデータソースにはアクセスしていません

MCP アダプターの受け入れ検証とデータソースの可用性は別々に集計されます。インターフェースが検出され、Schema が生成され、fixture_required または worker_failed にならずに AKShare の呼び出し経路に到達すれば、MCP アダプターは合格とみなされます。上流での失敗が隠されたり、成功と偽装されたりすることはありません。

レポートの生成

.venv\Scripts\python.exe -m akbridge.acceptance report

レポートは artifacts/acceptance/ 以下に書き込まれます。内容は SUMMARY.md/SUMMARY.en.md（二言語の概要）、summary.json（機械可読形式）、status.svg（README のステータス画像）、ledger.csv（項目ごとの結果）、manifest.json（完全な一覧）です。現在のベースラインの正確なバージョン、インターフェース数、各ステータスの集計は、受け入れ検証の概要を参照してください。失敗は上流ネットワーク、上流レスポンス、AKShare の実行エラー、上流タイムアウトに分類され、詳細な原因はインターフェースごとの詳細に記載されています。レポートは受け入れ検証コマンドによって生成されるため、AKShare のアップグレード時に README 内の数値を手動で同期する必要はありません。

自動受け入れ検証とメンテナンス

デフォルトのオフラインゲートはサードパーティのデータソースにアクセスせず、人や LLM も必要としません。

.venv\Scripts\python.exe -m akbridge.maintenance ci --strict `
  --baseline artifacts\acceptance\manifest.json `
  --current artifacts\maintenance\manifest.json `
  --catalog artifacts\catalog.json `
  --report artifacts\maintenance\latest.json

すべてのインターフェースを再検出し、すべての all ツールと固定の 3 つの router ツールを構築して検証し、入力 Schema と router インデックスを検証し、セマンティックカタログを生成し、インターフェースの追加／削除／シグネチャ／Schema の差分を比較します。インターフェースの削除、またはシグネチャ／Schema のリグレッションがある場合は、ゼロ以外の終了コードを返します。定期タスクで --check-latest を追加すると PyPI の最新 AKShare バージョンを確認できます。ネットワークが利用できない場合は unavailable として記録されます。新バージョンの検出時にタスクを失敗させるには、さらに --fail-on-update を追加します。

データソースにアクセスせず、アダプター契約のみを検証するには：

.venv\Scripts\python.exe -m akbridge.acceptance run --offline --workers 4

データソースの全件受け入れ検証で確認できるのは、上流のウェブサイト、CAPTCHA、ログイン、レート制限の状態であり、MCP アダプターが正しく動作するかどうかではありません。そのため、独立したネットワークプローブタスクとして実行してください。

.venv\Scripts\python.exe -m akbridge.maintenance ci --provider --timeout 60 --workers 4

自動メンテナンスワークフローは毎週オフライン処理を実行してレポートをアップロードします。データソースプローブワークフローは毎月 1 日と 15 日に、分離環境で全件受け入れ検証を実行します。詳細なルールは自動受け入れ検証とメンテナンスの説明を参照してください。

信頼性とセキュリティ

読み取り専用インターフェースでは、環境変数を使ってプロセス内キャッシュ、レート制限、再試行、サーキットブレーカーを有効にできます。

$env:AKBRIDGE_CACHE_TTL = "60"
$env:AKBRIDGE_RATE_LIMIT_SECONDS = "0.2"
$env:AKBRIDGE_MAX_ATTEMPTS = "2"
$env:AKBRIDGE_CIRCUIT_FAILURE_THRESHOLD = "5"
$env:AKBRIDGE_CALL_TIMEOUT = "120"

プロキシは標準の HTTP_PROXY/HTTPS_PROXY に加え、専用エイリアスの AKBRIDGE_HTTP_PROXY、AKBRIDGE_HTTPS_PROXY、AKBRIDGE_ALL_PROXY、AKBRIDGE_NO_PROXY もサポートしています。トークン、パスワード、Cookie、API Key は、受け入れ検証ログと構造化診断でマスキングされます。set_*、ログイン、設定関連のインターフェースは読み取り専用ではないと判定され、キャッシュも自動再試行も行われません。代替データソースは名前から自動推測されず、意味的な同等性が確認されたインターフェースに対して CallExecutor.register_fallback() を使い、明示的に登録する必要があります。

実行中のプロセスは MCP リソース akbridge://metrics を通じて、呼び出し回数、失敗数、再試行数、キャッシュヒット数、処理時間のカウントを提供します。AKBRIDGE_JSON_LOGS=1 を設定すると、再試行の診断情報が JSON Lines 形式で stderr に書き込まれ、stdio MCP プロトコルを汚染しません。

ネットワーク経由でデプロイする場合は、Streamable HTTP トランスポート（0.2.0 以降。MCP 2025-03-26 仕様に対応）の使用を推奨します。以前の SSE トランスポートも引き続き利用できますが、deprecated としてマークされています。

# 推荐：Streamable HTTP
.venv\Scripts\python.exe -m akbridge.server --transport http --mode router --host 127.0.0.1 --port 8000

# 旧版（deprecated）
.venv\Scripts\python.exe -m akbridge.server --transport sse --mode router --host 127.0.0.1 --port 8000

HTTP エンドポイントはデフォルトで /mcp に配置され、AKBRIDGE_HTTP_PATH で上書きできます。--http-json-response を指定すると、SSE ストリームではなく純粋な JSON を強制的に返すため、SSE ストリームに対応していないクライアントも接続できます。DNS rebinding 対策はデフォルトで有効です。ローカルバインドではデフォルトで localhost、127.0.0.1、[::1] が許可され、任意のポートを伴う形式も対象となります。カスタムドメインは --http-allowed-host で指定し、ブラウザーのクロスオリジン Origin は --http-allowed-origin で明示的に指定する必要があります。対応する環境変数は、カンマ区切りの AKBRIDGE_HTTP_ALLOWED_HOSTS と AKBRIDGE_HTTP_ALLOWED_ORIGINS です。環境変数 AKBRIDGE_HTTP_BEARER_TOKEN で bearer-token 認証を有効にできます。外部にデプロイする場合は、引き続き TLS とリバースプロキシのアクセス制御を設定することを推奨します。以前の SSE にはこれらの Host/Origin と bearer-token による保護がないため、信頼できるローカル環境で使用するか、認証済みのリバースプロキシの背後に配置してください。

テスト

.venv\Scripts\python.exe -m pytest -q

関数の検出、Schema の生成、セマンティック検索、DataFrame 変換、3 種類の結果モード、再試行／キャッシュ／サーキットブレーカー／マスキング、manifest ゲート、オフライン受け入れ検証に加え、実際の MCP stdio クライアントとのハンドシェイクや複雑なツール呼び出しも対象としています。受け入れ検証用パラメーターセットはすべてローカルにあり、手作業、人、LLM、サードパーティへのネットワークリクエストは不要です。

よくある質問

サービスを起動しても何も出力されません。 stdio MCP サービスでは正常な動作です。MCP クライアントからサービスを起動して管理してください。ブラウザーページが表示されることを期待しないでください。

ツールがネットワークエラーを返します。 AKShare は複数のサードパーティのデータウェブサイトに依存しています。まずツールのタイムアウトを延長して再試行してください。それでも失敗が続く場合は、ledger.csv のエラーの種類を確認し、接続失敗、上流の形式変更、AKShare の解析エラーのいずれかを判断してください。

返されるデータが大きすぎます。 サービスはデフォルトで最大 5,000 行をシリアライズし、結果に row_count と truncated を返します。起動時に変更できます。

.venv\Scripts\python.exe -m akbridge.server --row-limit 1000

AKShare のアップグレード後にインターフェース数が変わりました。 manifest と全件受け入れ検証を再実行してください。実行時の検出メカニズムによって、新たに追加された公開呼び出し可能インターフェースは自動的に公開されますが、シグネチャの変更とデータソースのリグレッションは引き続き確認してください。

現在の制限と今後の方向性

現在の制限：

• 組み込み Skill は MCP サービス経由で公開される汎用的な実行時呼び出し手順であり、クライアントモジュールとして自動インストールされません。クライアントや金融分野ごとにインストールできる Skills はまだありません。
• RAG はインターフェースカタログと語彙検索のみで、金融知識、用語マッピング、ベクトル検索、再ランキングが不足しています。

今後の方向性：

• 主要な LLM クライアントや Agent フレームワーク向けに、インストール可能で組み合わせて使える金融 Skills を提供します。
• 高頻度インターフェースに、人手で調整したツールの説明、パラメーターの意味、呼び出し例、結果の要約を追加します。
• 出典とバージョンを備えた金融ナレッジベースと、中国語・英語の用語適応レイヤーを構築します。
• ハイブリッド RAG 検索と自動受け入れ検証を提供し、ナレッジ検索、インターフェース選択、パラメーターの完全性を継続的に評価します。

ドキュメントとコントリビューション

• 自動受け入れ検証とメンテナンス / 自動受け入れ検証とメンテナンス
• セキュリティポリシー / セキュリティポリシー

Issue と Pull Request を歓迎します。提出前にコントリビューションガイドをお読みください。

ライセンス

AKBridge は MIT License の下でオープンソースとして公開されています。