valueledger

valueledger

valueledger is a small local bridge to FolioFact's hosted MCP server, a read-only research service for value investors: it tracks well-known funds and the investors behind them, follows their 13F-style holdings quarter by quarter, and layers company financials, earnings reports, insider transactions and options data on top.

The bridge keeps no research data of its own. It serves the upstream server's tool list locally, exactly as captured from the live endpoint, and forwards each tool call upstream, returning the result untouched. Every tool in the captured surface reads; nothing in it places a trade, moves money, or sends anything anywhere.

Tools

• search — bounded cross-domain search across funds, stocks and insider transactions. Optional: query.
• get_fund — one tracked fund's latest filing and its investors. Required: slug.
• fund_holdings — a fund's current portfolio positions with quarter-over-quarter change. Required: slug.
• fund_history — quarter-by-quarter filing history plus a summary of turnover, concentration and favourites. Required: slug.
• get_stock — one company as held by tracked funds: holders, values and last-quarter moves. Required: ticker.
• get_investor — one investor's portfolio links and featured fund. Required: slug.
• insider_feed — recent Form 4/5 insider transactions across all held stocks, newest first. Optional: filter, q, page, per_page, sort, dir.
• fetch_page — an allowlisted public page (blog posts, static pages, the agent discovery doc) as markdown or text. Required: path.
• stock_earnings — the latest cited AI Earnings Report for one stock. Required: ticker; optional: period, include_full.
• stock_financials — financial statements (yearly and quarterly) and the valuation summary for one stock. Required: ticker.
• stock_insiders — recent Form 4/5 insider transactions for one company. Required: ticker.
• stock_options — the daily 30-day implied-volatility history for one company. Required: ticker.
• compare_stocks — aligned side-by-side comparison of 2-6 stocks: valuation, latest financial point, fund conviction and insider activity. Required: tickers; optional: insider_window.

Several stock-level tools are marked in their upstream descriptions as requiring FolioFact Pro; the bridge forwards calls either way and passes the upstream answer through unchanged.

Configuration

• FOLIOFACT_MCP_URL (optional) — override the upstream endpoint. Defaults to https://foliofact.com/mcp. (The override hook is this rebuild's own labelled reconstruction.)
• FOLIOFACT_API_KEY (optional) — when set, every upstream request carries an X-Api-Key: <key> header (the header name comes from the upstream's registry record). When it is not set, no key header is sent. (Forwarding the key from this variable is also a labelled reconstruction; the original surface was captured keyless.)

Forwarding mechanics

On the first tool call the client opens a streamable HTTP session with the upstream: a JSON-RPC initialize request (protocolVersion 2025-03-26, clientInfo name valueledger), then a notifications/initialized notification, then the tools/call request carrying the caller's arguments unchanged. When the upstream answers initialize with an Mcp-Session-Id header, that value rides on every later request of the session, which is reused for the life of the process. Replies may arrive as plain JSON or as server-sent events; both are read.

Successful upstream results pass through verbatim, including any isError flag the upstream sets. Failures — a JSON-RPC error, a non-2xx status, an unreadable response, or a request that cannot be completed — come back as an isError result whose text starts with valueledger error: (this rendering is this rebuild's own labelled reconstruction).

CLI

Each tool is also a subcommand taking one JSON argument string (omit it for tools that take none):

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

Exit codes: 0 on success, 1 on an isError result, 2 on a usage error.

MCP server

npx -y @reneturcios/valueledger mcp

MCP client config:

{
  "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

The container's default command is mcp, so the first form is a stdio MCP server; any other arguments reach the CLI normally.

Development

npm install
npm run build
npm test
npm run dev

The test suite runs entirely against a stubbed JSON-RPC upstream — no live network calls.

License

MIT — see LICENSE.