India Finance MCP

India Finance MCP

一个通过模型上下文协议（MCP）向大模型和 Agent 提供印度金融数据的 MCP 服务，并为非 MCP 使用者提供配套的 REST API。

单一 TypeScript 代码库，支持两种部署目标：

• 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 和实体代码。	离线（模 36 校验和）	无

计划在 v1.1 中推出：

工具	用途	来源
get_stock_quote	获取在 NSE/BSE 上市股票的最新报价。	Yahoo Finance 代理（RELIANCE.NS 格式的代码）

---

快速开始

作为 MCP 客户端使用（Claude Desktop、Cursor 等）

有三种方式可选：

选项 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 的待机模式后，将 MCP 客户端指向 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

如需交互式界面，请使用 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 函数，以及一个 *_TOOL 常量，将它们与工具的 MCP 名称和描述组合在一起。两个入口会复用此契约。
3. 接入 MCP——在 src/mcp/index.ts 中通过 server.addTool({...}) 接入。工具结果必须以 JSON 字符串形式返回。
4. 接入 REST——在 src/rest/app.ts 中添加路由，使用 <schema>.safeParse 解析查询参数，调用 execute，并返回 c.json(...)。

代码库遵循的优化原则是：一套逻辑实现、一个契约、两种传输方式。

传输方式检测（Apify / FastMCP 入口）

src/mcp/index.ts 会在启动时选择传输方式：

触发条件	传输方式	使用场景
设置了 APIFY_CONTAINER_PORT	在该端口上使用 httpStream	Apify Actor 运行时
FASTMCP_TRANSPORT=http-stream	在 PORT 上使用 httpStream（默认 8080）	自托管 HTTP
两者均未设置	stdio	Claude Desktop、本地命令行、FastMCP 检查器

Cloudflare Workers 上的 MCP（不使用 FastMCP）

Workers 部署通过 src/rest/mcp-handler.ts 中手写的 JSON-RPC 处理程序提供 MCP 服务，因为 FastMCP 会引入无法打包到 Workers 的仅限 Node 的依赖项。该处理程序实现了 initialize、notifications/initialized（通过 HTTP 202 确认）、ping、tools/list 和 tools/call。工具输入架构通过 zod-to-json-schema 从 FastMCP 入口使用的同一组 zod 架构生成。因此两个入口提供完全相同的工具集合，只有底层框架不同。

无状态：没有会话 ID，也没有 SSE 流。每个 POST 都是一个 JSON-RPC 请求，并返回一个 JSON 响应（通知则返回 202）。

缓存

core/amfi.ts 中的 getNavRecords() 会缓存解析后的 AMFI 文件，内存 TTL 为 1 小时，并会对进行中的请求去重（并发调用共享同一个 fetch promise）。

• 在 Node/Apify 上，缓存会在进程的整个生命周期内跨请求保留。
• 在 Cloudflare Workers 上，缓存按 isolate 隔离——冷启动的 isolate 会重新获取数据。若要跨 isolate 缓存，请在 wrangler.toml 中绑定 KV 命名空间（文件中已有注释形式的存根），并在获取 AMFI 数据之前短路返回。

AMFI 每个工作日约在 IST 晚上 9–11 点发布一次当日 NAV 文件。

模块解析注意事项

tsconfig.json 使用 moduleResolution: "Bundler" 和 verbatimModuleSyntax: true。src/ 文件之间的导入必须以 .js 结尾，即使源文件是 .ts：

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——Cloudflare Workers 无需预先构建。

npm run build                      # tsc → dist/

测试方法

• tests/amfi.test.ts 会解析一个 fixture 字符串，涵盖类别标题、AMC 标题、空的 ;;;;; 行和 NAV 为 N.A. 的行。扩展 fixture，而不是模拟 fetch。
• tests/gstin.test.ts 涵盖有效 GSTIN、长度/格式/州/PAN 错误以及校验和错误案例。错误州和错误 PAN 的测试会先重新计算有效校验和，以隔离要测试的错误——添加新的验证规则时，这一点很重要。
• 从 core/amfi.ts 导出的 _resetCacheForTesting() 可供未来需要重新测试 fetch 路径的测试使用。

---

部署

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 控制台中启用待机模式，以使 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——添加跨 isolate 缓存是显而易见的下一项基础设施改动。

---

项目结构

.
├── .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