Protocollo MCP — SCORPIOX CODE

Panoramica

scorpiox code implementa il Model Context Protocol (MCP) come server C nativo. Il livello MCP funziona su stdio usando il framing JSON-RPC 2.0 — il client AI si connette via stdin/stdout e chiama gli strumenti tramite messaggi JSON strutturati. Tutti i 13 strumenti sono compilati nel binario da sx_tools.c senza dipendenze runtime.

# MCP server architecture (from sx_tools.c)

stdin  ──▶  JSON-RPC parser  ──▶  tool dispatcher  ──▶  result  ──▶  stdout

# All tools compiled into single static binary
# Source: scorpiox/libsxutil/sx_tools.c
# Zero runtime dependencies — no Node.js, no Python, no JVM

Livello di Trasporto

The MCP server uses stdio as its transport — the simplest, most reliable pipe. The AI client spawns the scorpiox binary and communicates via stdin/stdout using newline-delimited JSON-RPC 2.0 messages. No HTTP server, no WebSocket, no port binding.

# Transport: stdio (stdin/stdout)
# Framing: newline-delimited JSON-RPC 2.0
# Each message is a single JSON object terminated by \n

# Client sends request →
{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}

# Server responds ←
{"jsonrpc": "2.0", "id": 1, "result": {"tools": [...]}}

Handshake di Inizializzazione

Before calling tools, the client must complete the MCP initialization handshake. This establishes the protocol version and declares capabilities.

# Step 1: Client sends initialize request
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {
  "protocolVersion": "2024-11-05",
  "capabilities": {},
  "clientInfo": {"name": "claude-ai", "version": "1.0"}
}}

# Step 2: Server responds with capabilities
{"jsonrpc": "2.0", "id": 1, "result": {
  "protocolVersion": "2024-11-05",
  "capabilities": {"tools": {}},
  "serverInfo": {"name": "scorpiox-code", "version": "1.0.0"}
}}

# Step 3: Client sends initialized notification
{"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}

Metodi JSON-RPC

The MCP server handles 4 JSON-RPC methods. All tool invocations go through tools/call.

Metodo	Direzione	Description
`initialize`	client → server	Initialize MCP session with protocol version and client capabilities
`notifications/initialized`	client → server	Notification sent after successful initialization handshake
`tools/list`	client → server	List all tools available from the MCP server
`tools/call`	client → server	Call a specific tool with JSON arguments and receive result

# Example: calling the Bash tool
{"jsonrpc": "2.0", "id": 42, "method": "tools/call", "params": {
  "name": "Bash",
  "arguments": {"command": "ls -la /tmp", "timeout": 5000}
}}

# Server response
{"jsonrpc": "2.0", "id": 42, "result": {
  "content": [{"type": "text", "text": "total 48\ndrwxrwxrwt 12 root root ..."}],
  "isError": false
}}

Catalogo Strumenti (13)

All tools are implemented in scorpiox/libsxutil/sx_tools.c and compiled into the static binary. Each tool declares a JSON Schema for input validation.

Bash shell

Execute a bash command

Parametri: command, timeout

Richiesto: command

ReadImage filesystem

Read an image file and display it visually

Parametri: file_path

Richiesto: file_path

ReadDocs web

Fetch URL content as markdown via headless browser

Parametri: url, format, wait_ms

Richiesto: url

WebSearch search

Search the web using 11 engines concurrently

Parametri: query

Richiesto: query

TaskManager workflow

Manage persistent tasks with create/add/complete

Parametri: action, query, task_id, step_id, text

Richiesto: action, query

PlanMode workflow

Manage plan mode for complex tasks

Parametri: action, goal, plan_file

Richiesto: action

AskUserQuestion interaction

Ask interactive multiple-choice questions via TUI

Parametri: questions_json

Richiesto: questions_json

InvokeSkill workflow

Invoke a skill by name for reusable workflows

Parametri: skill_name, arguments

Richiesto: skill_name

BackgroundBash shell

Execute bash command in background, returns immediately

Parametri: command

Richiesto: command

ReadBgOutput shell

Read new output from a background task

Parametri: task_id

Richiesto: task_id

ListBgTasks shell

List all background tasks with status and runtime

Parametri: —

Richiesto: —

KillBgTask shell

Kill a running background task by ID

Parametri: task_id

Richiesto: task_id

SetCallback workflow

Manage scheduled callback messages with repeats

Parametri: action, message, delay_seconds, repeat_count, callback_id

Richiesto: action

Riferimento Schema Strumenti

Complete input_schema for each tool, as declared in the tools/list response.

Bash shell

Parametri	Type	Status	Description
`command`	`string`	required	The bash command to execute
`timeout`	`integer`	optional	Timeout in milliseconds (default: 30000)

ReadImage filesystem

Parametri	Type	Status	Description
`file_path`	`string`	required	The absolute path to the image file

ReadDocs web

Parametri	Type	Status	Description
`url`	`string`	required	The URL to fetch
`format`	`string`	optional	Output format: text, html, or markdown
`wait_ms`	`integer`	optional	Wait time for page load in ms

WebSearch search

Parametri	Type	Status	Description
`query`	`string`	required	The search query

TaskManager workflow

Parametri	Type	Status	Description
`action`	`string`	required	Action: create, add, complete, list, pending, switch
`query`	`string`	required	The search query
`task_id`	`integer`	optional	Task ID
`step_id`	`integer`	optional	Step ID
`text`	`string`	optional	Task name or step text

PlanMode workflow

Parametri	Type	Status	Description
`action`	`string`	required	Action: enter, exit, status, json, reset
`goal`	`string`	optional	Goal/description
`plan_file`	`string`	optional	Path to markdown plan file

AskUserQuestion interaction

Parametri	Type	Status	Description
`questions_json`	`string`	required	JSON string with questions and options

InvokeSkill workflow

Parametri	Type	Status	Description
`skill_name`	`string`	required	The skill name to invoke
`arguments`	`string`	optional	Arguments to pass to the skill

BackgroundBash shell

Parametri	Type	Status	Description
`command`	`string`	required	The bash command to execute

ReadBgOutput shell

Parametri	Type	Status	Description
`task_id`	`integer`	required	The task ID returned by BackgroundBash

KillBgTask shell

Parametri	Type	Status	Description
`task_id`	`integer`	required	The task ID to kill

SetCallback workflow

Parametri	Type	Status	Description
`action`	`string`	required	Action: set, list, cancel
`message`	`string`	optional	Callback message
`delay_seconds`	`integer`	optional	Seconds to wait (1-3600)
`repeat_count`	`integer`	optional	Times to fire before cancel
`callback_id`	`integer`	optional	Callback slot ID

Configurazione

MCP is enabled by default. The server advertises tools capability during initialization. Configuration is handled via scorpiox-env.txt.

# scorpiox-env.txt — MCP-related settings

TOOLS=true                  # Enable MCP tool serving (default: true)
STREAMING=true              # Stream tool results as they arrive
MODEL=sonnet                # AI model for tool-use conversations

# The MCP server binary path is auto-detected:
# Linux:   ~/.scorpiox/scorpiox-code
# macOS:   ~/.scorpiox/scorpiox-code
# Windows: %USERPROFILE%\.scorpiox\scorpiox-code.exe

# Client config (e.g., Claude Desktop mcp_servers.json):
# {"scorpiox": {"command": "~/.scorpiox/scorpiox-code", "args": []}}