Skip to content

Feat/engine mcp #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dedalik merged 2 commits into from
Aug 19, 2026
Merged

Feat/engine mcp #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5521579
feat(mcp): add @kiploks/engine-mcp for AI agent backtest analysis
dedalik Aug 19, 2026
8750b5f
docs(mcp): clean MCP code and document agent usage in README
dedalik Aug 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 88 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -244,29 +244,99 @@ Details: [`docs/BOT_INTEGRATIONS.md`](docs/BOT_INTEGRATIONS.md)

## Packages

| Package | Role |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `@kiploks/engine-core` | `analyze()`, `analyzeFromTrades()`, `analyzeFromWindows()`, `buildPathMonteCarloSimulation()`, `runProfessionalWfa()` |
| `@kiploks/engine-contracts` | Versioned TypeScript types and constants. Import these for type safety in your own code. |
| `@kiploks/engine-adapters` | `csvToTrades` / streaming CSV to `Trade[]` (Freqtrade-shaped **JSON** is not parsed here; map to `Trade[]` in your layer). |
| `@kiploks/engine-cli` | `npx kiploks analyze` - run analysis from JSON file, upload to cloud, run conformance tests |
| `@kiploks/engine-test-vectors` | Golden JSON fixtures for regression tests |
| Package | Role |
| --- | --- |
| `@kiploks/engine-core` | `analyze()`, WFA, Monte Carlo, professional report |
| `@kiploks/engine-contracts` | Versioned TypeScript types |
| `@kiploks/engine-adapters` | CSV to `Trade[]` |
| `@kiploks/engine-cli` | CLI + local UI orchestrator |
| `@kiploks/engine-mcp` | MCP server for AI agents |
| `@kiploks/engine-test-vectors` | Golden fixtures for regression tests |

---

## AI agents (MCP)

Use `@kiploks/engine-mcp` so Cursor, Claude Desktop, or any MCP client can analyze backtests and fetch reports locally - no cloud account required.

### 1. Add MCP server

**Cursor** (Settings -> MCP or `.cursor/mcp.json`):

```json
{
"mcpServers": {
"kiploks": {
"command": "npx",
"args": ["-y", "@kiploks/engine-mcp"],
"env": {
"KIPLOKS_ORCHESTRATOR_URL": "http://127.0.0.1:41731"
}
}
}
}
```

From a repo checkout after `npm run build -w @kiploks/engine-mcp`:

```json
{
"mcpServers": {
"kiploks": {
"command": "node",
"args": ["packages/mcp-server/dist/index.js"]
}
}
}
```

### 2. Analyze trades (no UI)

Ask your agent to call `kiploks_analyze_trades` with a CSV or JSON `Trade[]` file.

Or use CLI:

```bash
npx kiploks analyze-trades ./trades.json --json \
--in-sample-months 6 --out-of-sample-months 2 --step rolling
```

### 3. Freqtrade backtests (with UI)

Start the local orchestrator:

```bash
npx -y @kiploks/engine-cli ui --no-open
```

Typical agent flow:

1. `kiploks_orchestrator_status`
2. `kiploks_register_freqtrade_path` with your Freqtrade install path
3. `kiploks_bootstrap_integration`
4. `kiploks_list_backtests`
5. `kiploks_run_backtest_analysis` with `selected_artifact_keys`
6. `kiploks_get_report` -> open `{orchestrator_url}/ui/#report={id}`

If integration routes return `401`, set `KIPLOKS_ORCHESTRATOR_TOKEN` from `kiploks-freqtrade/kiploks.json` (`api_token`).

Full guide: [`docs/AI_AGENTS.md`](docs/AI_AGENTS.md)

---

## Documentation

| Topic | Link |
| ------------------------------------------ | --------------------------------------------------------------------------------------- |
| **Which function to call** (start here) | [`docs/ENTRYPOINTS.md`](docs/ENTRYPOINTS.md) |
| WFA methodology | [`docs/WFA_PROFESSIONAL.md`](docs/WFA_PROFESSIONAL.md) |
| Path Monte Carlo | [`docs/MONTE_CARLO_PATH.md`](docs/MONTE_CARLO_PATH.md) |
| Freqtrade / OctoBot (separate Python repos) | [`docs/BOT_INTEGRATIONS.md`](docs/BOT_INTEGRATIONS.md) |
| Reproducibility and hashes | [`docs/OPEN_CORE_REPRODUCIBILITY.md`](docs/OPEN_CORE_REPRODUCIBILITY.md) |
| Error catalog | [`docs/ERROR_CATALOG.md`](docs/ERROR_CATALOG.md) |
| Local user guide | [`docs/OPEN_CORE_LOCAL_USER_GUIDE.md`](docs/OPEN_CORE_LOCAL_USER_GUIDE.md) |
| Examples and output explorer | [`docs/examples/result-layout-demo.html`](docs/examples/result-layout-demo.html) |
| Research articles | [kiploks.com/research](https://kiploks.com/research) |
| Topic | Link |
| --- | --- |
| Which function to call | [`docs/ENTRYPOINTS.md`](docs/ENTRYPOINTS.md) |
| AI agents and MCP | [`docs/AI_AGENTS.md`](docs/AI_AGENTS.md) |
| WFA methodology | [`docs/WFA_PROFESSIONAL.md`](docs/WFA_PROFESSIONAL.md) |
| Path Monte Carlo | [`docs/MONTE_CARLO_PATH.md`](docs/MONTE_CARLO_PATH.md) |
| Freqtrade / OctoBot | [`docs/BOT_INTEGRATIONS.md`](docs/BOT_INTEGRATIONS.md) |
| Reproducibility | [`docs/OPEN_CORE_REPRODUCIBILITY.md`](docs/OPEN_CORE_REPRODUCIBILITY.md) |
| Error catalog | [`docs/ERROR_CATALOG.md`](docs/ERROR_CATALOG.md) |
| Local user guide | [`docs/OPEN_CORE_LOCAL_USER_GUIDE.md`](docs/OPEN_CORE_LOCAL_USER_GUIDE.md) |
| Examples | [`docs/examples/result-layout-demo.html`](docs/examples/result-layout-demo.html) |

---

Expand Down
133 changes: 133 additions & 0 deletions docs/AI_AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
# AI agents and MCP

This guide explains how **other users** of the open-source Kiploks engine can let AI agents analyze backtests and fetch reports - without Kiploks cloud or private SaaS.

## What an agent can do

| Capability | Requires orchestrator? | MCP tool / CLI |
|------------|------------------------|----------------|
| WFA from trades CSV/JSON | No | `kiploks_analyze_trades` / `kiploks analyze-trades` |
| Full report from integration JSON | No | `kiploks_analyze_integration_payload` |
| List Freqtrade backtests on disk | Yes | `kiploks_list_backtests` |
| Run Freqtrade bridge + WFA | Yes | `kiploks_run_backtest_analysis` |
| Open report in local UI | Yes | `kiploks_get_report` -> `/ui/#report=<id>` |

## Quick start for users

### 1. Install engine CLI

```bash
npx -y @kiploks/engine-cli ui --no-open
```

Orchestrator listens on `http://127.0.0.1:41731` (or next free port). UI: `/ui/`.

### 2. Add MCP server to your agent

Package: `@kiploks/engine-mcp`

**Cursor** (`.cursor/mcp.json` or Settings -> MCP):

```json
{
"mcpServers": {
"kiploks": {
"command": "npx",
"args": ["-y", "@kiploks/engine-mcp"]
}
}
}
```

**Claude Desktop** (`claude_desktop_config.json`): same block under `mcpServers`.

### 3. Analyze without Freqtrade (trades only)

No orchestrator needed. Agent tool:

- `kiploks_analyze_trades` with `input_path` pointing to CSV or JSON `Trade[]`

Or CLI:

```bash
kiploks analyze-trades ./trades.json --json \
--in-sample-months 6 --out-of-sample-months 2 --step rolling
```

Sample output: `docs/examples/sample-output/wfa-from-trades.json`

### 4. Freqtrade end-to-end flow

Prerequisites on the user's machine:

- Freqtrade install (path known to the user)
- Docker (if using default `docker` integration mode)
- Orchestrator running (`kiploks ui --no-open`)

Agent steps:

1. `kiploks_orchestrator_status` - confirm orchestrator is up
2. `kiploks_register_freqtrade_path` - `path` = Freqtrade root
3. `kiploks_bootstrap_integration` - clones `kiploks-freqtrade` into that repo
4. `kiploks_list_backtests` - discover artifacts under `user_data/backtest_results`
5. `kiploks_run_backtest_analysis` - pass `selected_artifact_keys` from step 4
6. `kiploks_get_report` - full `TestResultData` JSON
7. Share UI link: `{orchestrator_url}/ui/#report={report_id}`

If integration upload needs Bearer auth, set in MCP env:

```json
"env": {
"KIPLOKS_ORCHESTRATOR_TOKEN": "<api_token from kiploks.json after bootstrap>"
}
```

## Architecture

```mermaid
flowchart LR
Agent[AI Agent]
MCP[@kiploks/engine-mcp]
Core[@kiploks/engine-core]
Orch[kiploks ui orchestrator]
Bridge[kiploks-freqtrade run.py]
Agent --> MCP
MCP -->|trades / payload files| Core
MCP -->|HTTP| Orch
Orch --> Bridge
Bridge -->|POST /api/integration/results| Orch
Orch -->|reports| MCP
```

- **Standalone analysis** uses `@kiploks/engine-core` directly inside the MCP process.
- **Freqtrade flow** uses the existing local orchestrator HTTP API (same as the web UI).
- **Cloud upload** is optional: users can still use `kiploks upload --cloud` with `KIPLOKS_API_KEY`; MCP does not require it.

## Programmatic API (no MCP)

For custom agents or scripts, use the same building blocks:

```ts
import { analyzeFromTrades } from "@kiploks/engine-core";
import { buildTestResultDataFromUnified } from "@kiploks/engine-core/server";
import { mapPayloadToUnified } from "@kiploks/engine-core";
```

See [ENTRYPOINTS.md](./ENTRYPOINTS.md) for choosing the right entrypoint.

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| MCP cannot connect to orchestrator | Start `kiploks ui --no-open`; check `KIPLOKS_ORCHESTRATOR_URL` |
| Empty backtest list | Register Freqtrade path; run a backtest; bootstrap bridge |
| `401` on integration POST | Set `KIPLOKS_ORCHESTRATOR_TOKEN` from `kiploks.json` |
| Docker upload `Connection refused` | From container use `host.docker.internal`, not `localhost` |
| `analyze_trades` rejects JSON | Input must be `Trade[]` array, not raw Freqtrade export |

## Related docs

- [packages/mcp-server/README.md](../packages/mcp-server/README.md) - MCP tool reference
- [BOT_INTEGRATIONS.md](./BOT_INTEGRATIONS.md) - Freqtrade/OctoBot bridges
- [LOCAL_ORCHESTRATOR_UI_ARCHITECTURE.md](./LOCAL_ORCHESTRATOR_UI_ARCHITECTURE.md) - HTTP routes
- [OPEN_CORE_LOCAL_USER_GUIDE.md](./OPEN_CORE_LOCAL_USER_GUIDE.md) - local user setup
1 change: 1 addition & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ Authoritative copies of engine-focused guides live **in this folder** so they sh
| [`OSS_PUBLIC_REPO_SYNC.md`](OSS_PUBLIC_REPO_SYNC.md) | Repository layout, one `VERSION`, `sync-versions`, publish notes |
| [`RELEASE_CHECKLIST.md`](../RELEASE_CHECKLIST.md) | Pre-release checks (tests, docs vs contracts) |
| [`BOT_INTEGRATIONS.md`](BOT_INTEGRATIONS.md) | Freqtrade / OctoBot Python integrations (optional path without npm engine) |
| [`AI_AGENTS.md`](AI_AGENTS.md) | MCP server and agent workflows for backtest analysis |
| [`MONTE_CARLO_SIMULATION_IMPLEMENTATION.md`](MONTE_CARLO_SIMULATION_IMPLEMENTATION.md) | **Monte Carlo index** - path MC vs professional window bootstrap, links to guides |
| [`MONTE_CARLO_PATH.md`](MONTE_CARLO_PATH.md) | **Path-based Monte Carlo (user guide)** - `buildPathMonteCarloSimulation`, API, limits, reproducibility |

Expand Down
Loading
Loading