quaq-mcp

name

quaq-mcp

description

Use this skill when the user wants to configure, debug, or work with the quaq MCP (Model Context Protocol) server. Triggers include: setting up quaq as an MCP server, configuring Claude Code or other AI agents to use quaq tools, debugging MCP JSON-RPC communication, understanding quaq MCP tools/resources/prompts, testing the MCP server, or integrating quaq into an agentic workflow. Also use when the user asks about "mcp", "agentic backend", "stdio JSON-RPC", or "tool integration".

Quaq MCP Server Skill

Overview

The quaq MCP server (quaq-core mcp) turns the Zig backtesting engine into a live agentic backend. AI agents call tools directly via stdio JSON-RPC 2.0 — validate, backtest, sweep, explain — and iterate autonomously at ~600K bars/sec.

Starting the Server

cd core && zig build run -- mcp

The server reads JSON-RPC 2.0 messages from stdin (one per line) and writes responses to stdout. All diagnostics go to stderr.

Claude Code Configuration

Add to your MCP settings (.claude/settings.json or project-level):

{
  "mcpServers": {
    "quaq": {
      "command": "/path/to/quaq-core",
      "args": ["mcp"]
    }
  }
}

Or if building from source:

{
  "mcpServers": {
    "quaq": {
      "command": "/path/to/quaq/core/zig-out/bin/quaq-core",
      "args": ["mcp"]
    }
  }
}

Available Tools (7)

Tool	Description	Required Args
validate_strategy	Validate TOML strategy for schema errors	toml (string)
run_backtest	Run full backtest, return metrics	toml (string)
explain_strategy	Parse strategy, return structure	toml (string)
sweep_params	Parameter sweep over values	toml, node_id, param, values[]
list_datasets	List CSV/Parquet files in data/	none
describe_dataset	Load dataset, return stats	path (string)
fetch_data	Fetch Binance klines to CSV	symbol, timeframe, optional start/end

Available Resources (2 static + 1 template)

URI	Description
quaq://schema/nodes	Full 145+ node catalog as JSON
quaq://engine/version	Engine version, modes, node count
quaq://schema/node/{kind}	Individual node spec (template)

Available Prompts (3)

Prompt	Description	Args
analyze_backtest	Structured performance analysis	metrics_json
debug_strategy	Fix validation errors systematically	errors_json
suggest_improvements	Parameter tuning + alternative indicators	metrics_json, toml

Protocol Details

• Protocol: JSON-RPC 2.0 over stdio
• Protocol Version: 2025-06-18
• Server Name: quaq
• Engine Version: 2.0.0

Lifecycle

1. Client sends initialize with capabilities
2. Server responds with serverInfo and capabilities (tools, resources, prompts)
3. Client sends notifications/initialized
4. Client can now call tools/call, resources/read, prompts/get, etc.

Error Codes

Code	Meaning
-32700	Parse error (malformed JSON)
-32601	Method not found
-32602	Invalid params

Testing the Server

# Initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | quaq-core mcp

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | quaq-core mcp

# Validate a strategy (use python for proper JSON escaping)
python3 -c '
import json
toml = open("strategy.toml").read()
msg = json.dumps({"jsonrpc":"2.0","id":3,"method":"tools/call",
  "params":{"name":"validate_strategy","arguments":{"toml":toml}}})
print(msg)
' | quaq-core mcp

Architecture

• Source: core/src/mcp_server.zig
• Entry: core/src/main.zig → mcp subcommand → mcp_server.runMcp()
• Delegates to: engine.zig, agent_api.zig, schema_catalog.zig, ir_toml.zig, data.zig, fetch_binance.zig
• Module registration: root.zig → pub const mcp_server

Typical Agentic Workflow

1. Agent reads quaq://schema/nodes resource to understand available node types
2. Agent composes a TOML strategy
3. Agent calls validate_strategy to check for errors
4. Agent fixes errors using debug_strategy prompt
5. Agent calls run_backtest to get performance metrics
6. Agent calls sweep_params to optimize parameters
7. Agent uses analyze_backtest prompt to evaluate results
8. Agent iterates on the strategy using suggest_improvements prompt