agentleFS
INo-xiousINo-xious/stockbit-mcp/CLAUDE.md

stockbit-mcp

CLAUDE.md58 starsChanged 3 months agoMITView on GitHub

Notes for an AI assistant working on this repository. Human contributors want CONTRIBUTING.md, which this does not duplicate. An MCP server over Stockbit's private JSON API. Real-money execution is removed. Brokerage portfolio and history are read-only; paper_* is the local ledger and virtual_* is Stockbit's website simulation. Never add a live-order, subscription, deposit or withdrawal route. The generated docs/TOOLS.md is the authoritative tool inventory. The full gate before a commit is all six. CI runs them on three operating systems…

The file

We split this CLAUDE.md into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Never invent a number: If a field could not be read, it is absent — not zero, not a default.

    line 57
  2. Very specific:

    Never widen an evidence claim: Every tool DECLARES its evidence — { evidence } on the tool or on define.family() — and one that declares …

    line 60
  3. Distinctive:

    Fixtures carry no real data: No real account numbers, names or watchlists.

    line 70
  4. Distinctive:

    No AI co-author trailers in commits: Never commit on main; use a task branch.

    line 71

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

Notes for an AI assistant working on this repository. Human contributors want CONTRIBUTING.md, which this does not duplicate.

What this is

An MCP server over Stockbit's private JSON API. Real-money execution is removed. Brokerage portfolio and history are read-only; paper_* is the local ledger and virtual_* is Stockbit's website simulation. Never add a live-order, subscription, deposit or withdrawal route. The generated docs/TOOLS.md is the authoritative tool inventory.

Commands

npm run typecheck     # src/, bin/, scripts/
npm test              # the whole suite, offline, no skips
npm run build         # cleans dist/ first
npm run smoke         # starts the built binary over stdio and asks it what it registered
npm run check:pack    # asserts npm publish would ship the build and nothing else
npm run docs:tools    # regenerates docs/TOOLS.md — run it after touching ANY tool

The full gate before a commit is all six. CI runs them on three operating systems and two Node versions.

The map

Path
src/http/routes/The closed route table — Explicit request shapes. The security boundary.
src/http/transport.tsWhat enforces it.
src/auth/Login capture, three token stores, refresh with a cross-process lock.
src/core/One module per Stockbit domain. The readers everything else stands on.
src/analysis/Indicators, patterns, strategies, backtests, scans, position sizing.
src/render/Pure SVG. No browser.
src/tools/MCP registration, one module per family. _define.ts is the door.
src/trading/, src/eipo/, src/virtual/Read-only accounts and explicitly separated simulations.
src/alerts/Rules, the daemon, delivery.
docs/adr/Every decision that changed what this server may do.

Three invariants. Do not break them; each has a test.

  1. Nothing reaches a Stockbit host outside src/http/routes/. Adding a non-GET route requires an ADR before the code lands. test/transport.test.ts.
  2. define.write never adds to the handler map workflow_run reads. A saved recipe is data, and data must not be able to place an order. test/tools.test.ts.
  3. No module under src/tools/, src/trading/ or src/eipo/ may import saveSettings. A server that can widen its own permissions has no permissions. test/settings.test.ts.

Rules that are easy to get wrong

  • Run npm run docs:tools after touching a tool. docs/TOOLS.md is generated and a test fails if it is stale.
  • Add a new write tool's name to WRITES in test/tools.test.ts. That list is deliberately hand-written; deriving it would make the test agree with the code.
  • Never invent a number. If a field could not be read, it is absent — not zero, not a default. readFrom names the wire key a value came from; unmappedKeys names what was not recognised, and on account data the values are dropped because an unmapped field there may be an account number.
  • Never widen an evidence claim. Every tool DECLARES its evidence — { evidence } on the tool or on define.family() — and one that declares nothing fails to register rather than defaulting to observed. A description that says the route has never been observed while the declaration claims more throws at registration. The full map is hand-written in test/tools.test.ts beside WRITES, and for the same reason. Settling one takes a live call, not an edit.
  • Never write a secret anywhere. Tokens, PINs and bot tokens are matched by shape as well as by key. When adding an error path, ask what the message could contain: a fetch failure quotes the URL, and a Telegram URL contains the bot token.
  • The tests are offline. fetch is stubbed; every test file sets STOCKBIT_FORCE_FILE_STORE=1 and a temp STOCKBIT_STORE_DIR before its imports, because module state is captured at import.
  • Fixtures carry no real data. No real account numbers, names or watchlists.
  • No AI co-author trailers in commits. Never commit on main; use a task branch.

Vocabulary

CONTEXT.md is the glossary — one meaning per word, and the code uses those words. The evidence ladder (Observed / Read-back / Projected) is load-bearing, not decoration.

Execution boundaries

Real-money routes and execution modules have been removed. Historical order-entry ADRs are superseded by ADR-0012. Local paper orders still require preview tickets, and simulated Stockbit orders may only use the virtual route allowlist. Never claim a simulation reached the exchange. Unknown write outcomes must never be automatically retried. No tool accepts a trading PIN.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.