India Finance MCP

India Finance MCP

LLM とエージェントにインドの金融データを提供する Model Context Protocol（MCP）サーバーです。MCP を利用しないクライアント向けに、並行して REST API も提供します。

単一の TypeScript コードベースから、2 つのデプロイ先に対応します。

• MCP サーバー（FastMCP、Node）— Apify Actor としてデプロイされます。Claude Desktop、Cursor、または MCP 対応クライアントに接続できます。
• REST ミラー（Cloudflare Workers 上の Hono）— HTTP クライアント向けです。RapidAPI 経由で収益化できます。

2026-05-04 時点で稼働中です。

対象	URL	トランスポート
Apify Actor	https://apify.com/vamppog/india-finance-mcp	FastMCP 経由で /mcp に MCP（Streamable HTTP）
Cloudflare Workers	https://india-finance-mcp.vamp-fa0.workers.dev	POST /mcp に MCP（JSON-RPC）＋ /api/* に REST

---

できること

ツール	用途	データソース	認証
get_mutual_fund_nav	AMFI スキームコードまたは自由入力のスキーム名を指定して、インドの任意の投資信託の最新 NAV を検索します。	AMFI — 毎日更新	不要
validate_gstin	15 文字の GSTIN の構造とチェックサムを検証します。州、埋め込み PAN、事業体コードを解析します。	オフライン（mod-36 チェックサム）	不要

v1.1 で予定：

ツール	用途	データソース
get_stock_quote	NSE/BSE 上場株式の最新株価を取得します。	Yahoo Finance プロキシ（RELIANCE.NS 形式のシンボル）

---

クイックスタート

MCP クライアントとして（Claude Desktop、Cursor など）

次の 3 つの方法があります。

オプション A — Cloudflare Workers（常時稼働、Apify のスタンバイは不要）：

POST https://india-finance-mcp.vamp-fa0.workers.dev/mcp

MCP Streamable HTTP / JSON-RPC に対応しています。HTTP トランスポートに対応するすべての MCP クライアントで使用できます。

オプション B — Apify Actor（FastMCP ベース）：

Apify コンソールで Actor のスタンバイモードを有効にしたら、クライアントから Actor の /mcp にある MCP エンドポイントに接続します。

オプション C — ローカル stdio：

git clone <this-repo>
cd "Indian finance MCP"
npm install
npm run dev:mcp        # stdio transport for local MCP clients

対話型 UI を使うには、FastMCP インスペクターを使用します。

npm run inspect        # opens fastmcp dev UI

プレーン HTTP を使う MCP クライアントとして（curl）

# initialize
curl -X POST https://india-finance-mcp.vamp-fa0.workers.dev/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

# tools/list
curl -X POST https://india-finance-mcp.vamp-fa0.workers.dev/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# tools/call
curl -X POST https://india-finance-mcp.vamp-fa0.workers.dev/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"validate_gstin","arguments":{"gstin":"27AAPFU0939F1ZV"}}}'

REST クライアントとして

# Mutual fund NAV by AMFI scheme code
curl 'https://india-finance-mcp.vamp-fa0.workers.dev/api/mutual-fund/nav?code=122639'

# Free-text scheme name search
curl 'https://india-finance-mcp.vamp-fa0.workers.dev/api/mutual-fund/nav?q=parag+parikh+flexi+cap+direct&limit=5'

# GSTIN validation
curl 'https://india-finance-mcp.vamp-fa0.workers.dev/api/gstin/validate?gstin=27AAPFU0939F1ZV'

サンプルレスポンス（NAV）：

{
  "query": "122639",
  "matches": [
    {
      "schemeCode": "122639",
      "isinGrowth": "INF879O01027",
      "isinReinvestment": null,
      "schemeName": "Parag Parikh Flexi Cap Fund - Direct Plan - Growth",
      "nav": 91.2902,
      "date": "30-Apr-2026",
      "category": "Open Ended Schemes(Equity Scheme - Flexi Cap Fund)",
      "amc": "PPFAS Mutual Fund"
    }
  ],
  "asOf": "30-Apr-2026",
  "source": "amfi"
}

サンプルレスポンス（GSTIN）：

{
  "gstin": "27AAPFU0939F1ZV",
  "valid": true,
  "errors": [],
  "parts": {
    "stateCode": "27",
    "stateName": "Maharashtra",
    "pan": "AAPFU0939F",
    "entityCode": "1",
    "defaultLetter": "Z",
    "checksum": "V"
  }
}

---

アーキテクチャ

src/
├── core/                # Pure logic + I/O. Workers-safe. No fastmcp/hono imports.
│   ├── amfi.ts          # Fetch + parse + 1h TTL cache + search for AMFI NAV file
│   ├── gstin.ts         # Mod-36 checksum, state-code table, structural checks
│   └── types.ts         # Shared record/result types
├── tools/               # MCP-tool contracts: zod schema + execute() + _TOOL const
│   ├── mutual-fund-nav.ts
│   └── validate-gstin.ts
├── mcp/
│   └── index.ts         # FastMCP entry — addTool(...) per tool, stdio or http-stream
└── rest/
    ├── app.ts           # Hono app — REST routes + POST /mcp (JSON-RPC)
    ├── mcp-handler.ts   # Workers-safe MCP JSON-RPC dispatcher (no fastmcp)
    ├── worker.ts        # Cloudflare Workers entry: { fetch: app.fetch }
    └── node.ts          # Local-dev entry via @hono/node-server

ツールの追加方法

1. ロジックを src/core/ に記述します — 純粋関数と必要なキャッシュを実装します。このレイヤーは依存関係を持たないようにしてください。Node（Apify）と Workers ランタイムの両方で動作する必要があります。
2. コントラクトを src/tools/ に定義します — zod スキーマ、execute 関数、およびツールの MCP 名と説明をまとめた *_TOOL 定数をエクスポートします。このコントラクトは両方のエントリで再利用されます。
3. src/mcp/index.ts で MCP に接続します — server.addTool({...}) を使います。ツールの結果は JSON 文字列として返す必要があります。
4. src/rest/app.ts で REST に接続します — ルートを追加し、<schema>.safeParse でクエリパラメーターを解析し、execute を呼び出して、c.json(...) を返します。

このコードベースが最適化の基準とするルールは、ロジックの実装は 1 つ、コントラクトも 1 つ、トランスポートは 2 つです。

トランスポートの検出（Apify / FastMCP エントリ）

起動時に src/mcp/index.ts がトランスポートを選択します。

条件	トランスポート	用途
APIFY_CONTAINER_PORT が設定されている	そのポートで httpStream	Apify Actor ランタイム
FASTMCP_TRANSPORT=http-stream	PORT（デフォルト 8080）で httpStream	セルフホスト可能な HTTP
どちらにも該当しない	stdio	Claude Desktop、ローカル CLI、FastMCP インスペクター

Cloudflare Workers 上的 MCP（不使用 FastMCP）

Workers のデプロイでは、FastMCP に Workers 用のバンドルに含められない Node 専用の依存関係が含まれるため、src/rest/mcp-handler.ts に独自実装した JSON-RPC ハンドラーを通じて MCP を提供します。このハンドラーは、initialize、notifications/initialized（HTTP 202 で応答）、ping、tools/list、tools/call を実装しています。ツールの入力スキーマは、FastMCP エントリと同じ zod スキーマから zod-to-json-schema を使って出力されます。そのため、どちらのエントリも同一のツール群を公開し、異なるのは基盤となるフレームワークだけです。

ステートレスです。セッション ID も SSE ストリームもありません。各 POST は 1 つの JSON-RPC リクエストを受け取り、1 つの JSON レスポンス（通知の場合は 202）を返します。

キャッシュ

core/amfi.ts の getNavRecords() は、解析済みの AMFI ファイルをメモリ内で 1 時間キャッシュし、進行中のリクエストを重複排除します（同時に呼び出された場合は、単一の fetch プロミスを共有します）。

• Node／Apify では、プロセスの存続期間中、リクエストをまたいでキャッシュが保持されます。
• Cloudflare Workers では、キャッシュはアイソレートごとです。コールド状態のアイソレートでは再取得します。アイソレートをまたいだキャッシュには、wrangler.toml で KV 名前空間をバインドし（コメントアウトされたひな形はすでにあります）、AMFI の取得前に処理を早期終了させてください。

AMFI は営業日の毎日、IST の午後 9 時から 11 時ごろに NAV ファイルを公開します。

モジュール解決時の注意点

tsconfig.json では moduleResolution: "Bundler" と verbatimModuleSyntax: true を使用しています。src/ ファイル間のインポートは、ソースが .ts であっても、末尾を .js にする必要があります。

import { getNavRecords } from "../core/amfi.js";   // ✅
import { getNavRecords } from "../core/amfi";      // ❌ build will fail

tsc と Wrangler／esbuild の両方で正しく解決されます。

Workers の互換性に関する制約

src/rest/worker.ts と、その推移的なインポートは Workers に対応している必要があります。

• ✅ グローバルの fetch、純粋なロジック、Hono。
• ❌ process.env、@hono/node-server、src/mcp/ 配下のもの、fastmcp のもの。FastMCP には Workers 用のバンドルに含められない Node 専用の依存関係が含まれています。

現在の worker.ts → app.ts → tools/* → core/{amfi,gstin}.ts というインポートグラフはこの制約を守っています。この状態を維持してください。

---

開発

セットアップ

npm install                        # ~225 packages

よく使うコマンド

npm test                           # all vitest tests
npx vitest run tests/gstin.test.ts -t "checksum"   # single test by file + name
npx vitest                         # watch mode
npx tsc --noEmit                   # typecheck only

npm run dev:mcp                    # tsx watch — stdio MCP server
npm run inspect                    # fastmcp dev — interactive MCP inspector UI
npm run dev:rest                   # tsx watch — Hono on http://localhost:3000
npm run cf:dev                     # wrangler dev — Workers runtime on http://localhost:8787

npx tsx scripts/smoke.ts           # end-to-end smoke test against live AMFI

ビルド

dist/ のビルドが必要なのは Apify の Docker イメージのみです。Dockerfile はビルダーステージで tsc を実行します。Wrangler は src/rest/worker.ts を直接バンドルするため、CF Workers 用の事前ビルドは不要です。

npm run build                      # tsc → dist/

テスト方針

• tests/amfi.test.ts では、カテゴリーヘッダー、AMC ヘッダー、空の ;;;;; 行、N.A. の NAV 行を含むフィクスチャ文字列を解析します。fetch をモックするのではなく、フィクスチャを拡張してください。
• tests/gstin.test.ts では、有効な GSTIN、長さ／形式／州／PAN のエラー、チェックサム不正のケースを確認します。州と PAN の不正をテストする際は、まず有効なチェックサムを再計算して、テスト対象のエラーだけを切り分けます。新しい検証ルールを追加する際に重要です。
• 将来のテストで fetch の経路を再テストする必要がある場合に備え、_resetCacheForTesting() は core/amfi.ts からエクスポートされています。

---

デプロイ

Apify（MCP サーバー）

npm install -g apify-cli
apify login
apify push --wait-for-finish 600

設定は .actor/actor.json にあります。webServerMcpPath フィールドにより、Apify は MCP トラフィックを /mcp にルーティングします。Dockerfile はマルチステージ（Alpine、ビルド → ランタイム）で、FASTMCP_TRANSPORT=http-stream と FASTMCP_STATELESS=true を指定してサーバーを起動します。

ビルドが成功したら、Apify コンソールで Standby モードを有効にしてください。これにより MCP エンドポイントにアクセスできるようになります。この操作はコンソールでのみ行え、CLI による代替手段はありません。

Cloudflare Workers（REST ミラー）

npx wrangler login
npx wrangler deploy

wrangler.toml では account_id を固定しています（開発者ごとに設定し、このリポジトリのデフォルトは Vamp アカウントです）。別のアカウントを使用するには、CLOUDFLARE_ACCOUNT_ID で上書きするか、ファイルを編集してください。

ビルド成果物は単一のバンドル（約 190 KiB／gzip 圧縮で約 38 KiB）です。KV バインディングはまだありません。アイソレートをまたいだキャッシュの追加が、次に取り組むべき明らかなインフラ変更です。

---

プロジェクト構成

.
├── .actor/              # Apify actor metadata (actor.json, input_schema.json)
├── src/                 # See architecture diagram above
├── tests/               # vitest suites
├── scripts/smoke.ts     # End-to-end smoke test
├── Dockerfile           # Multi-stage build for Apify
├── wrangler.toml        # Cloudflare Workers config
├── tsconfig.json        # Bundler-mode + verbatimModuleSyntax
├── vitest.config.ts
└── package.json

---

データソースと法的注意事項

• AMFI NAV ファイル（https://www.amfiindia.com/spages/NAVAll.txt）— 公開されており、認証は不要です。出典の表示が推奨されています。すべての NAV レスポンスに source: "amfi" フィールドが含まれます。
• GSTIN の検証 — すべてオフラインで行われます。mod-36 チェックサムは、GSTN が公開しているアルゴリズムです。このツールは GSTN ポータルを呼び出さず、GSTIN が現在有効か、または特定の事業体に登録されているかを確認しません。文字列の形式が正しいことのみを確認します。
• 株価（予定）— Yahoo Finance には公式の無料利用規約がありません。利用は自己責任で行い、株価ツールを商用化する前に有料プロバイダーへの切り替えを検討してください。

---

ロードマップ

• v0.1 — get_mutual_fund_nav、validate_gstin、Apify と CF Workers にデプロイ済み
• v1.1 — get_stock_quote（Yahoo Finance プロキシ、NSE + BSE）
• v1.2 — get_market_summary（指数のスナップショット）
• インフラ — Workers で分離環境をまたいで永続化するための KV ベースの NAV キャッシュ
• 掲載 — Apify Store
• 掲載 — Smithery、Glama、mcp.so、PulseMCP、公式 MCP レジストリ

---

ライセンス

MIT