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…
In this repository9 other files it gives its agents.
- bandar-checkSkill
- chart-markupSkill
- morning-scanSkill
- stockbit-authSkill
- stockbit-statusSkill
- stock-deep-diveSkill
- strategy-backtestSkill
- trade-with-guardrailsSkill
- watchSkill
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
- Very specific: line 57
Never invent a number: If a field could not be read, it is absent — not zero, not a default.
- Very specific: line 60
Never widen an evidence claim: Every tool DECLARES its evidence — { evidence } on the tool or on define.family() — and one that declares …
- Distinctive: line 70
Fixtures carry no real data: No real account numbers, names or watchlists.
- Distinctive: line 71
No AI co-author trailers in commits: Never commit on main; use a task branch.
≈ “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.
Files
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 toolThe 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.ts | What 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.
- 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. define.writenever adds to the handler mapworkflow_runreads. A saved recipe is data, and data must not be able to place an order.test/tools.test.ts.- No module under
src/tools/,src/trading/orsrc/eipo/may importsaveSettings. 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:toolsafter touching a tool.docs/TOOLS.mdis generated and a test fails if it is stale. - Add a new write tool's name to
WRITESintest/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.
readFromnames the wire key a value came from;unmappedKeysnames 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 ondefine.family()— and one that declares nothing fails to register rather than defaulting toobserved. A description that says the route has never been observed while the declaration claims more throws at registration. The full map is hand-written intest/tools.test.tsbesideWRITES, 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
fetchfailure quotes the URL, and a Telegram URL contains the bot token. - The tests are offline.
fetchis stubbed; every test file setsSTOCKBIT_FORCE_FILE_STORE=1and a tempSTOCKBIT_STORE_DIRbefore 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.
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
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.

