Content
# stock-monitoring-kit
[English](README.md) | [简体中文](README.zh-CN.md)
A local-first, vendor-neutral toolkit for building market-monitoring agents. It packages deterministic technical indicators, shared schemas, provider contracts, versioned research prompts, reusable Agent Skills, and a local stdio MCP server.
This repository is the open core. Product UI, private watchlists, account data, commercial scoring weights, licensed data adapters, secrets, and cloud services deliberately stay outside it.
> For research and education only. This project does not provide personalized investment advice or trading execution.
## What is included
| Module | Purpose |
| --- | --- |
| `domain` | Zod schemas for OHLCV bars, watchlists, events, strategy settings, evidence, and reports |
| `indicator-engine` | Pure BBI, KDJ, MACD, volume-ratio, crossover, and explainable strategy functions |
| `provider-contracts` | Interfaces for user-supplied model, market-data, news, calendar, and prediction-market adapters |
| `prompt-pack` | Versioned premarket, postmarket, event-preread, and black-swan prompts |
| `workflow` | Local orchestration that connects watchlists, providers, indicators, and models |
| `mcp-server` | Local stdio MCP tools, prompts, and resources |
| `skills` | Four portable Agent Skills matching the research workflows |
See [Architecture](docs/architecture.md) for the open/closed boundary.
## Quick start
Requirements: Node.js 20 or newer.
```bash
npm install
npm run check
```
Use the deterministic engine:
```ts
import { evaluateStrategy } from "@stock-monitoring-kit/indicator-engine";
const result = evaluateStrategy(bars, {
volumeRatioThreshold: 1.5,
kdjOversold: 20,
kdjOverbought: 80
});
console.log(result.signals, result.notes);
```
The default strategy treats close-below-BBI, abnormal volume, KDJ extremes, and a latest MACD crossover as independent evidence. Scores are transparent defaults, not a proprietary model or a trade recommendation.
## Local MCP server
Build and run over stdio:
```bash
npm run build
npm run mcp
```
Example MCP client configuration after cloning:
```json
{
"mcpServers": {
"stock-monitoring-kit": {
"command": "node",
"args": ["/absolute/path/to/stock-monitoring-kit/packages/mcp-server/dist/index.js"]
}
}
}
```
Exposed tools:
- `compute_technical_series`
- `evaluate_strategy`
- `render_research_prompt`
Exposed prompts:
- `premarket-review`
- `postmarket-review`
- `event-preread`
- `black-swan-radar`
No HTTP server, cloud account, or project-owned API key is required.
## Bring your own providers
Implement the interfaces in `provider-contracts` inside your host app. Resolve API keys through the operating-system keychain or another host-controlled secret store; never embed them in a watchlist, prompt, repository, or mini-program bundle.
```ts
import type { ModelProvider } from "@stock-monitoring-kit/provider-contracts";
export const localModelAdapter: ModelProvider = {
id: "my-provider",
async generate(request, credential) {
// Resolve credential.id locally, call the chosen vendor, and return text.
throw new Error("Implement in the host application");
}
};
```
## Skills
Each directory under `skills/` is a standalone Agent Skill with `SKILL.md` and `agents/openai.yaml`. Install or link only the workflows you want. The skills can use the MCP tools when available and retain explicit fallback definitions when they are not.
## Design principles
- Local-first: user watchlists and model credentials remain under host control.
- Evidence-first: facts, consensus, prediction-market signals, and inference stay separate.
- Deterministic before generative: calculations are code; the model explains and connects evidence.
- Vendor-neutral: public packages define contracts, not licensed or secret adapters.
- Auditable: prompt versions, thresholds, timestamps, sources, and invalidations remain visible.
## Development
```bash
npm run typecheck
npm test
npm run build
```
Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Security issues belong in the process described in [SECURITY.md](SECURITY.md).
## License
Apache-2.0. See [LICENSE](LICENSE).
