quaq-mcp - SKILL.md Agent Skill

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

Client sends initialize with capabilities
Server responds with serverInfo and capabilities (tools, resources, prompts)
Client sends notifications/initialized
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

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