valueledger

valueledger

valueledger 是 FolioFact 托管 MCP 服务的一个小型本地桥接程序。该服务面向价值投资者，提供只读研究功能：追踪知名基金及其背后的投资者，按季度跟踪其 13F 风格的持仓，并叠加公司财务数据、财报、内部人士交易和期权数据。

该桥接程序不保存任何研究数据。它会在本地提供上游服务的工具列表，内容与从实时端点捕获的内容完全一致；并将每次工具调用转发到上游，原样返回结果。捕获到的工具全部是读取操作；其中没有任何工具会下单、转移资金或向任何地方发送内容。

工具

• search — 在基金、股票和内部人士交易领域进行范围受限的跨领域搜索。可选：query。
• get_fund — 获取一只受跟踪基金的最新申报及其投资者。必需：slug。
• fund_holdings — 获取一只基金的当前投资组合持仓及环比变化。必需：slug。
• fund_history — 按季度列出申报历史，并汇总换手率、集中度和偏好持仓。必需：slug。
• get_stock — 获取受跟踪基金持有的一家公司：持有人、持仓价值和上季度变动。必需：ticker。
• get_investor — 获取一位投资者的投资组合链接和精选基金。必需：slug。
• insider_feed — 汇总所有持仓股票近期的 Form 4/5 内部人士交易，按时间从新到旧排列。可选：filter、q、page、per_page、sort、dir。
• fetch_page — 将允许列表中的公共页面（博客文章、静态页面、Agent 发现文档）作为 Markdown 或文本获取。必需：path。
• stock_earnings — 获取一只股票最新的 AI Earnings Report 引用内容。必需：ticker；可选：period、include_full。
• stock_financials — 获取一只股票的财务报表（年度和季度）及估值摘要。必需：ticker。
• stock_insiders — 获取一家公司的近期 Form 4/5 内部人士交易。必需：ticker。
• stock_options — 获取一家公司的 30 天隐含波动率每日历史数据。必需：ticker。
• compare_stocks — 对 2-6 只股票进行对齐的并排比较：估值、最新财务数据点、基金信心度和内部人士活动。必需：tickers；可选：insider_window。

上游描述中有几项个股级工具标记为需要 FolioFact Pro；无论是否满足要求，桥接程序都会转发调用，并原样传递上游答复。

配置

• FOLIOFACT_MCP_URL（可选）— 覆盖上游端点。默认值为 https://foliofact.com/mcp。（此覆盖钩子是本次重建中特别标注的还原内容。）
• FOLIOFACT_API_KEY（可选）— 设置后，每个上游请求都会携带 X-Api-Key: <key> 请求头（请求头名称来自上游的注册记录）。未设置时，不会发送密钥请求头。（从此变量转发密钥也是本次重建中特别标注的还原内容；原始接口是在无密钥状态下捕获的。）

转发机制

首次调用工具时，客户端会与上游建立可流式传输的 HTTP 会话：发送 JSON-RPC initialize 请求（protocolVersion 为 2025-03-26，clientInfo 名称为 valueledger），然后发送 notifications/initialized 通知，接着发送携带调用方原样参数的 tools/call 请求。上游通过 initialize 响应返回 Mcp-Session-Id 请求头时，该值会随会话后续的每个请求发送；此会话会在进程运行期间重复使用。回复可能是纯 JSON，也可能是服务器发送事件；两种格式都会读取。

上游成功结果会逐字传递，包括上游设置的任何 isError 标志。失败情况——JSON-RPC 错误、非 2xx 状态、无法读取响应，或无法完成的请求——会以 isError 结果返回，其文本以 valueledger error: 开头（此错误呈现方式是本次重建中特别标注的还原内容）。

命令行

每个工具也是一个子命令，接受一个 JSON 参数 字符串（不需要参数的工具可省略）：

npx @reneturcios/valueledger search '{"query":"Pabrai"}'
npx @reneturcios/valueledger get_fund '{"slug":"pabrai-funds"}'
npx @reneturcios/valueledger get_stock '{"ticker":"BRK.A"}'
npx @reneturcios/valueledger compare_stocks '{"tickers":"AAPL,MSFT,GOOG"}'
npx @reneturcios/valueledger --version

退出代码：成功时为 0，结果包含 isError 时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/valueledger mcp

MCP 客户端配置：

{
  "mcpServers": {
    "valueledger": {
      "command": "npx",
      "args": ["-y", "@reneturcios/valueledger", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/valueledger
docker run --rm ghcr.io/cloudcorprecords/valueledger --version

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；其他参数都会正常传递给命令行。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全使用桩接的 JSON-RPC 上游服务运行，不会进行实时网络调用。

许可证

MIT——详见 LICENSE。