archivebox.mcp.server

Model Context Protocol (MCP) server implementation for ArchiveBox.

Dynamically exposes all ArchiveBox CLI commands as MCP tools by introspecting Click command metadata. Handles JSON-RPC 2.0 requests over stdio transport.

Module Contents

Classes

MCPJSONEncoder	Custom JSON encoder that handles Click sentinel values and other special types
MCPServer	Model Context Protocol server for ArchiveBox.

Functions

click_type_to_json_schema_type	Convert a Click parameter type to JSON Schema type definition
click_command_to_mcp_tool	Convert a Click command to an MCP tool definition with JSON Schema.
execute_click_command	Execute a Click command programmatically with given arguments.
run_mcp_server	Main entry point for MCP server

API

class archivebox.mcp.server.MCPJSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: json.JSONEncoder

Custom JSON encoder that handles Click sentinel values and other special types

Initialization

Constructor for JSONEncoder, with sensible defaults.

If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, float, bool or None. If skipkeys is True, such items are simply skipped.

If ensure_ascii is true, the output is guaranteed to be str objects with all incoming non-ASCII characters escaped. If ensure_ascii is false, the output can contain non-ASCII characters.

If check_circular is true, then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an RecursionError). Otherwise, no such check takes place.

If allow_nan is true, then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a ValueError to encode such floats.

If sort_keys is true, then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis.

If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.

If specified, separators should be an (item_separator, key_separator) tuple. The default is (’, ‘, ‘: ‘) if indent is None and (‘,’, ‘: ‘) otherwise. To get the most compact JSON representation, you should specify (‘,’, ‘:’) to eliminate whitespace.

If specified, default is a function that gets called for objects that can’t otherwise be serialized. It should return a JSON encodable version of the object or raise a TypeError.

default(o)

archivebox.mcp.server.click_type_to_json_schema_type(click_type: click.ParamType) → dict[str, Any]

Convert a Click parameter type to JSON Schema type definition

archivebox.mcp.server.click_command_to_mcp_tool(cmd_name: str, click_command: click.Command) → dict[str, Any]

Convert a Click command to an MCP tool definition with JSON Schema.

Introspects the Click command’s parameters to automatically generate the input schema without manual definition.

archivebox.mcp.server.execute_click_command(cmd_name: str, click_command: click.Command, arguments: dict) → dict

Execute a Click command programmatically with given arguments.

Returns MCP-formatted result with captured output and error status.

class archivebox.mcp.server.MCPServer

Model Context Protocol server for ArchiveBox.

Provides JSON-RPC 2.0 interface over stdio, dynamically exposing all Click commands as MCP tools.

Initialization

get_click_command(cmd_name: str) → click.Command | None

Get a Click command by name, with caching

handle_initialize(params: dict) → dict

Handle MCP initialize request

handle_tools_list(params: dict) → dict

Handle MCP tools/list request - returns all available CLI commands as tools

handle_tools_call(params: dict) → dict

Handle MCP tools/call request - executes a CLI command

handle_request(request: dict) → dict

Handle a JSON-RPC 2.0 request and return response.

Supports MCP methods: initialize, tools/list, tools/call

run_stdio_server()

Run the MCP server in stdio mode.

Reads JSON-RPC requests from stdin (one per line), writes JSON-RPC responses to stdout (one per line).

archivebox.mcp.server.run_mcp_server()

Main entry point for MCP server