MCPプロトコル — SCORPIOX CODE

概要

scorpiox codeはModel Context Protocol（MCP）をネイティブCサーバーとして実装しています。MCP層はJSON-RPC 2.0フレーミングでstdio上で動作し、AIクライアントはstdin/stdoutを通じて接続し、構造化JSONメッセージでツールを呼び出します。13のツールすべてがsx_tools.cからバイナリにコンパイルされ、ランタイム依存関係はゼロです。

# 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

トランスポート層

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

初期化ハンドシェイク

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メソッド

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

メソッド	方向	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
}}

ツールカタログ (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

パラメータ: command, timeout

必須: command

ReadImage filesystem

Read an image file and display it visually

パラメータ: file_path

必須: file_path

ReadDocs web

Fetch URL content as markdown via headless browser

パラメータ: url, format, wait_ms

必須: url

WebSearch search

Search the web using 11 engines concurrently

パラメータ: query

必須: query

TaskManager workflow

Manage persistent tasks with create/add/complete

パラメータ: action, query, task_id, step_id, text

必須: action, query

PlanMode workflow

Manage plan mode for complex tasks

パラメータ: action, goal, plan_file

必須: action

AskUserQuestion interaction

Ask interactive multiple-choice questions via TUI

パラメータ: questions_json

必須: questions_json

InvokeSkill workflow

Invoke a skill by name for reusable workflows

パラメータ: skill_name, arguments

必須: skill_name

BackgroundBash shell

Execute bash command in background, returns immediately

パラメータ: command

必須: command

ReadBgOutput shell

Read new output from a background task

パラメータ: task_id

必須: task_id

ListBgTasks shell

List all background tasks with status and runtime

パラメータ: —

必須: —

KillBgTask shell

Kill a running background task by ID

パラメータ: task_id

必須: task_id

SetCallback workflow

Manage scheduled callback messages with repeats

パラメータ: action, message, delay_seconds, repeat_count, callback_id

必須: action

ツールスキーマリファレンス

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

Bash shell

パラメータ	Type	Status	Description
`command`	`string`	required	The bash command to execute
`timeout`	`integer`	optional	Timeout in milliseconds (default: 30000)

ReadImage filesystem

パラメータ	Type	Status	Description
`file_path`	`string`	required	The absolute path to the image file

ReadDocs web

パラメータ	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

パラメータ	Type	Status	Description
`query`	`string`	required	The search query

TaskManager workflow

パラメータ	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

パラメータ	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

パラメータ	Type	Status	Description
`questions_json`	`string`	required	JSON string with questions and options

InvokeSkill workflow

パラメータ	Type	Status	Description
`skill_name`	`string`	required	The skill name to invoke
`arguments`	`string`	optional	Arguments to pass to the skill

BackgroundBash shell

パラメータ	Type	Status	Description
`command`	`string`	required	The bash command to execute

ReadBgOutput shell

パラメータ	Type	Status	Description
`task_id`	`integer`	required	The task ID returned by BackgroundBash

KillBgTask shell

パラメータ	Type	Status	Description
`task_id`	`integer`	required	The task ID to kill

SetCallback workflow

パラメータ	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

設定

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