MCP-Protokoll — SCORPIOX CODE

Übersicht

scorpiox code implementiert das Model Context Protocol (MCP) als nativen C-Server. Die MCP-Schicht läuft über stdio mit JSON-RPC 2.0 Framing — der AI-Client verbindet sich über stdin/stdout und ruft Tools über strukturierte JSON-Nachrichten auf. Alle 13 Tools werden aus sx_tools.c in die Binary kompiliert, ohne Laufzeitabhängigkeiten.

# 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

Transportschicht

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": [...]}}

Initialisierungs-Handshake

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": {}}

JSON-RPC-Methoden

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

Methode	Richtung	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
}}

Tool-Katalog (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

Parameter: command, timeout

Erforderlich: command

ReadImage filesystem

Read an image file and display it visually

Parameter: file_path

Erforderlich: file_path

ReadDocs web

Fetch URL content as markdown via headless browser

Parameter: url, format, wait_ms

Erforderlich: url

WebSearch search

Search the web using 11 engines concurrently

Parameter: query

Erforderlich: query

TaskManager workflow

Manage persistent tasks with create/add/complete

Parameter: action, query, task_id, step_id, text

Erforderlich: action, query

PlanMode workflow

Manage plan mode for complex tasks

Parameter: action, goal, plan_file

Erforderlich: action

AskUserQuestion interaction

Ask interactive multiple-choice questions via TUI

Parameter: questions_json

Erforderlich: questions_json

InvokeSkill workflow

Invoke a skill by name for reusable workflows

Parameter: skill_name, arguments

Erforderlich: skill_name

BackgroundBash shell

Execute bash command in background, returns immediately

Parameter: command

Erforderlich: command

ReadBgOutput shell

Read new output from a background task

Parameter: task_id

Erforderlich: task_id

ListBgTasks shell

List all background tasks with status and runtime

Parameter: —

Erforderlich: —

KillBgTask shell

Kill a running background task by ID

Parameter: task_id

Erforderlich: task_id

SetCallback workflow

Manage scheduled callback messages with repeats

Parameter: action, message, delay_seconds, repeat_count, callback_id

Erforderlich: action

Tool-Schema-Referenz

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

Bash shell

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

ReadImage filesystem

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

ReadDocs web

Parameter	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

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

TaskManager workflow

Parameter	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

Parameter	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

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

InvokeSkill workflow

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

BackgroundBash shell

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

ReadBgOutput shell

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

KillBgTask shell

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

SetCallback workflow

Parameter	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

Konfiguration

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": []}}