parra-mcp 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +69 -2
  2. package/bin/index.js +121 -0
  3. package/package.json +34 -4
package/README.md CHANGED
@@ -1,3 +1,70 @@
1
- # Temporary Holding Version
1
+ # parra-mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Official Model Context Protocol (MCP) bridge for **Parra Multi-Agent Lab** (`parra.ml`).
4
+
5
+ Connects **Claude Desktop**, **Cursor**, **Windsurf**, and autonomous AI agents directly to the **Vibe-Trading Backtest Engine** and **Bitcoin Microstructure & Liquidation Intelligence** in sub-10ms.
6
+
7
+ ---
8
+
9
+ ## 🚀 Quick Setup for Claude Desktop
10
+
11
+ Add this block to your `claude_desktop_config.json`:
12
+
13
+ ```json
14
+ {
15
+ "mcpServers": {
16
+ "parra-quant": {
17
+ "command": "npx",
18
+ "args": ["-y", "parra-mcp"],
19
+ "env": {
20
+ "PARRA_API_KEY": "your_api_key_here"
21
+ }
22
+ }
23
+ }
24
+ }
25
+ ```
26
+
27
+ *Don't have an API Key? Get one free at [https://parra.ml/app](https://parra.ml/app) or test with `pk_live_demo123456789`.*
28
+
29
+ ---
30
+
31
+ ## ⚡ Direct URL Setup (Cursor / Windsurf / OpenCode)
32
+
33
+ If your client supports remote HTTP MCP servers directly, you don't even need `npx`:
34
+
35
+ ```json
36
+ {
37
+ "mcpServers": {
38
+ "parra-quant": {
39
+ "url": "https://mcp.parra.ml/mcp",
40
+ "headers": {
41
+ "Authorization": "Bearer your_api_key_here"
42
+ }
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ ---
49
+
50
+ ## 🛠️ Available Tools
51
+
52
+ 1. **`run_predefined_strategy_backtest`**
53
+ * Execute automated quantitative backtests with real friction (commissions, slippage), Sharpe ratio, Sortino, Calmar, and win rate.
54
+ * Templates available: `ema_crossover`, `rsi_mean_reversion`, `momentum_breakout`.
55
+ 2. **`run_custom_strategy_backtest`**
56
+ * Feed custom Python `SignalEngine` classes to simulate proprietary alpha strategies.
57
+ 3. **`list_available_backtest_templates`**
58
+ * Inspect available quantitative strategy templates and parameters.
59
+ 4. **`get_crypto_funding_regime`**
60
+ * Dense statistical funding rate APR%, standard deviation, and regime classification (`neutral_equilibrium`, `extreme_greed_overleveraged_long`, `bearish_discount_short_crowded`).
61
+ 5. **`get_historical_stress_events`**
62
+ * Extreme historical liquidation cascades and leverage peaks (COVID crash, FTX collapse).
63
+ 6. **`get_funding_arbitrage_spread`**
64
+ * Cross-asset funding rate spreads (e.g. BTC vs ETH) for cash-and-carry and basis trading.
65
+
66
+ ---
67
+
68
+ ## 📜 License
69
+
70
+ MIT © [Parra Multi-Agent Lab](https://parra.ml)
package/bin/index.js ADDED
@@ -0,0 +1,121 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Parra Lab Remote MCP Bridge (Zero-Dependency Node.js Client)
4
+ *
5
+ * Connects local AI agent runtimes (Claude Desktop, Cursor, OpenCode)
6
+ * over standard stdio JSON-RPC to the authenticated Parra Lab Cloud Gateway.
7
+ */
8
+
9
+ import readline from 'node:readline';
10
+
11
+ const API_KEY = process.env.PARRA_API_KEY;
12
+ const GATEWAY_URL = (process.env.PARRA_GATEWAY_URL || 'https://mcp.parra.ml/mcp').replace(/\/+$/, '');
13
+
14
+ if (!API_KEY) {
15
+ process.stderr.write(
16
+ '[ERROR] Missing PARRA_API_KEY environment variable.\n' +
17
+ 'Get your API Key at https://parra.ml/app and configure it in your MCP client settings:\n' +
18
+ ' "env": { "PARRA_API_KEY": "pk_live_..." }\n'
19
+ );
20
+ process.exit(1);
21
+ }
22
+
23
+ const rl = readline.createInterface({
24
+ input: process.stdin,
25
+ output: process.stdout,
26
+ terminal: false,
27
+ });
28
+
29
+ let sessionId = null;
30
+
31
+ async function sendJsonRpc(line) {
32
+ const trimmed = line.trim();
33
+ if (!trimmed) return;
34
+
35
+ let payload;
36
+ try {
37
+ payload = JSON.parse(trimmed);
38
+ } catch (err) {
39
+ process.stderr.write(`[WARN] Invalid JSON received from client: ${err.message}\n`);
40
+ return;
41
+ }
42
+
43
+ const headers = {
44
+ 'Content-Type': 'application/json',
45
+ 'Accept': 'application/json, text/event-stream',
46
+ 'Authorization': `Bearer ${API_KEY}`,
47
+ };
48
+
49
+ if (sessionId) {
50
+ headers['mcp-session-id'] = sessionId;
51
+ }
52
+
53
+ try {
54
+ const res = await fetch(GATEWAY_URL, {
55
+ method: 'POST',
56
+ headers,
57
+ body: JSON.stringify(payload),
58
+ });
59
+
60
+ if (!res.ok) {
61
+ let errDetail = `HTTP ${res.status}`;
62
+ try {
63
+ const errJson = await res.json();
64
+ if (errJson && errJson.error) errDetail = errJson.error;
65
+ } catch {
66
+ // ignore
67
+ }
68
+
69
+ const errorRpc = {
70
+ jsonrpc: '2.0',
71
+ id: payload.id ?? null,
72
+ error: {
73
+ code: -32000,
74
+ message: `[Parra Lab Cloud Gateway Error] ${errDetail}`,
75
+ },
76
+ };
77
+ process.stdout.write(JSON.stringify(errorRpc) + '\n');
78
+ return;
79
+ }
80
+
81
+ const newSid = res.headers.get('mcp-session-id');
82
+ if (newSid) {
83
+ sessionId = newSid;
84
+ }
85
+
86
+ const contentType = res.headers.get('content-type') || '';
87
+ if (contentType.includes('text/event-stream')) {
88
+ const text = await res.text();
89
+ for (const eventLine of text.split('\n')) {
90
+ if (eventLine.startsWith('data: ')) {
91
+ const dataPayload = eventLine.slice(6).trim();
92
+ if (dataPayload) {
93
+ process.stdout.write(dataPayload + '\n');
94
+ }
95
+ }
96
+ }
97
+ } else {
98
+ const data = await res.text();
99
+ process.stdout.write(data.trim() + '\n');
100
+ }
101
+ } catch (netErr) {
102
+ const errorRpc = {
103
+ jsonrpc: '2.0',
104
+ id: payload.id ?? null,
105
+ error: {
106
+ code: -32603,
107
+ message: `Network error reaching Parra Lab Cloud Gateway (${GATEWAY_URL}): ${netErr.message}`,
108
+ },
109
+ };
110
+ process.stdout.write(JSON.stringify(errorRpc) + '\n');
111
+ }
112
+ }
113
+
114
+ rl.on('line', (line) => {
115
+ sendJsonRpc(line).catch((err) => {
116
+ process.stderr.write(`[ERROR] Uncaught exception: ${err.message}\n`);
117
+ });
118
+ });
119
+
120
+ process.on('SIGINT', () => process.exit(0));
121
+ process.on('SIGTERM', () => process.exit(0));
package/package.json CHANGED
@@ -1,6 +1,36 @@
1
1
  {
2
2
  "name": "parra-mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "description": "Zero-dependency Model Context Protocol (MCP) bridge for Parra Quantitative Lab & Vibe-Trading Engine",
5
+ "main": "bin/index.js",
6
+ "type": "module",
7
+ "bin": {
8
+ "parra-mcp": "bin/index.js",
9
+ "parra-quant": "bin/index.js"
10
+ },
11
+ "files": [
12
+ "bin",
13
+ "README.md"
14
+ ],
15
+ "scripts": {
16
+ "start": "node bin/index.js",
17
+ "test": "node test/test-e2e.js"
18
+ },
19
+ "keywords": [
20
+ "mcp",
21
+ "model-context-protocol",
22
+ "claude",
23
+ "cursor",
24
+ "quantitative",
25
+ "backtesting",
26
+ "crypto",
27
+ "vibe-trading",
28
+ "liquidations",
29
+ "duckdb"
30
+ ],
31
+ "author": "Parra Multi-Agent Lab <hola@parra.ml>",
32
+ "license": "MIT",
33
+ "engines": {
34
+ "node": ">=18.0.0"
35
+ }
36
+ }