script-kit-mcp

Script Kit MCP Implementation

MCP (Model Context Protocol) enables AI agents to interact with Script Kit via JSON-RPC 2.0.

Architecture Overview

mcp_server.rs      HTTP server on localhost:43210
    |
    v
mcp_protocol.rs    JSON-RPC 2.0 request/response handling
    |
    +---> mcp_kit_tools.rs      kit/* namespace tools
    +---> mcp_script_tools.rs   scripts/* namespace tools
    +---> mcp_resources.rs      Resource endpoints
    +---> mcp_streaming.rs      SSE streaming & audit logging

Core Modules

mcp_protocol.rs - JSON-RPC 2.0 Protocol

Handles request parsing, method routing, and response generation.

Supported Methods:

• initialize - Returns server capabilities
• tools/list - Lists all available tools
• tools/call - Executes a tool
• resources/list - Lists all resources
• resources/read - Reads a resource

Key Types:

pub struct JsonRpcRequest {
    pub jsonrpc: String,  // Must be "2.0"
    pub id: Value,        // Request identifier
    pub method: String,   // Method name
    pub params: Value,    // Optional parameters
}

pub struct JsonRpcResponse {
    pub jsonrpc: String,
    pub id: Value,
    pub result: Option<Value>,  // Success
    pub error: Option<JsonRpcError>,  // Failure
}

Error Codes:

• -32700 PARSE_ERROR - Invalid JSON
• -32600 INVALID_REQUEST - Invalid request object
• -32601 METHOD_NOT_FOUND - Method not found
• -32602 INVALID_PARAMS - Invalid parameters
• -32603 INTERNAL_ERROR - Internal error

mcp_server.rs - HTTP Server

Lightweight HTTP server using std::net (no async runtime).

Features:

• Runs on localhost:43210 (configurable via MCP_PORT)
• Bearer token authentication from ~/.scriptkit/agent-token
• Discovery file at ~/.scriptkit/server.json
• Health endpoint at GET /health
• RPC endpoint at POST /rpc

Server Lifecycle:

let server = McpServer::with_defaults()?;
let handle = server.start()?;  // Starts in background thread
// ... server runs ...
handle.stop();  // Graceful shutdown

mcp_kit_tools.rs - Kit Tools

Built-in tools in the kit/* namespace.

Available Tools:

Tool Result Format:

pub struct ToolResult {
    pub content: Vec<ToolContent>,
    #[serde(rename = "isError")]
    pub is_error: Option<bool>,  // Serializes as "isError" in JSON
}

mcp_script_tools.rs - Script Tools

Auto-generates MCP tools from scripts with schema.input.

Tool Naming: scripts/{script-name-slug}

• "Create Note" -> scripts/create-note
• "Git Commit" -> scripts/git-commit

Script Requirements:

• Must have schema = { input: {...} } in metadata
• Empty schema.input is excluded

Key Functions:

// Generate tool definitions from scripts
pub fn get_script_tool_definitions(scripts: &[Arc<Script>]) -> Vec<ToolDefinition>

// Check if tool is in scripts/* namespace
pub fn is_script_tool(name: &str) -> bool

// Handle script tool calls
pub fn handle_script_tool_call(scripts, tool_name, arguments) -> ScriptToolResult

mcp_resources.rs - Resources

Read-only data accessible via resource URIs.

Available Resources:

Resource Content Format:

pub struct ResourceContent {
    pub uri: String,
    #[serde(rename = "mimeType")]
    pub mime_type: String,  // Serializes as "mimeType", value is "application/json"
    pub text: String,       // JSON stringified content
}

mcp_streaming.rs - SSE Streaming & Audit

SSE Event Types:

• progress - Progress updates
• output - Output data
• error - Error messages
• complete - Completion notification

SSE Format:

event: progress
data: {"message":"working","progress":50}

Audit Logging: Writes to ~/.scriptkit/logs/mcp-audit.jsonl

pub struct AuditLogEntry {
    pub timestamp: String,    // ISO 8601
    pub method: String,       // Tool/method name
    pub params: Value,        // Parameters
    pub duration_ms: u64,     // Duration
    pub success: bool,        // Success flag
    pub error: Option<String>, // Error if failed
}

Usage Patterns

Adding a New Kit Tool

1. Add tool definition in mcp_kit_tools.rs:

ToolDefinition {
    name: "kit/new-tool".to_string(),
    description: "Description".to_string(),
    input_schema: serde_json::json!({
        "type": "object",
        "properties": {
            "param": { "type": "string" }
        }
    }),
}

2. Handle in handle_kit_tool_call:

"kit/new-tool" => ToolResult { ... }

Making a Script Callable via MCP

Add schema to script metadata:

// Name: My Script
// Description: Does something
schema = {
  input: {
    title: { type: "string", required: true, description: "Title" },
    count: { type: "number", min: 0, max: 100 }
  }
}

Adding a New Resource

1. Add to get_resource_definitions():

McpResource {
    uri: "new://resource".to_string(),
    name: "New Resource".to_string(),
    description: Some("Description".to_string()),
    mime_type: "application/json".to_string(),
}

2. Handle in read_resource():

"new://resource" => read_new_resource(...)

Testing

All modules use TDD with tests written first.

# Run MCP tests
cargo test mcp_

# Run specific module tests
cargo test mcp_protocol
cargo test mcp_server
cargo test mcp_kit_tools
cargo test mcp_script_tools
cargo test mcp_resources
cargo test mcp_streaming

References

• MCP Architecture - Detailed module interactions
• JSON-RPC 2.0 Spec
• MCP Specification