Module server 

MCP-compatible HTTP server.

Exposes Context Harness functionality via a JSON HTTP API suitable for integration with Cursor, Claude, and other MCP-compatible AI tools.

All tools — built-in (search, get, sources), Lua scripts, and custom Rust trait implementations — are registered in a unified ToolRegistry and dispatched through the same POST /tools/{name} handler.

Agents (named personas with system prompts and tool scoping) are registered in an AgentRegistry and discoverable/resolvable via dedicated endpoints.

Endpoints

Method	Path	Description
GET	/tools/list	List all registered tools with schemas
POST	/tools/{name}	Call any registered tool by name
GET	/agents/list	List all registered agents with metadata
POST	/agents/{name}/prompt	Resolve an agent’s system prompt
GET	/health	Health check (returns version)

Error Contract

All error responses follow the schema defined in docs/SCHEMAS.md:

{ "error": { "code": "bad_request", "message": "query must not be empty" } }

Error codes: bad_request (400), not_found (404), embeddings_disabled (400), timeout (408), tool_error (500), internal (500).

CORS

All origins, methods, and headers are permitted to support browser-based clients and cross-origin MCP tool calls.

Cursor Integration

Start the server and point Cursor at the /mcp endpoint:

{
  "mcpServers": {
    "context-harness": {
      "url": "http://127.0.0.1:7331/mcp"
    }
  }
}

Structs

AgentListResponse 🔒

JSON response body for GET /agents/list.

AppError 🔒

Internal error type that converts into an Axum HTTP response.

AppState 🔒

Shared application state passed to all route handlers via Axum’s State extractor.

ErrorBody 🔒

JSON error response body, matching docs/SCHEMAS.md error schema.

ErrorDetail 🔒

Inner error detail with a machine-readable code and human-readable message.

HealthResponse 🔒

JSON response body for GET /health.

ToolListResponse 🔒

JSON response body for GET /tools/list.

Functions

bad_request 🔒

Constructs a 400 Bad Request error.

classify_tool_error 🔒

Inspects tool execution errors and maps them to the most appropriate HTTP status code. This allows built-in tools to signal client errors (e.g. empty query → 400, document not found → 404) without needing a custom error type in the Tool trait.

handle_health 🔒

Handler for GET /health.

handle_list_agents 🔒

Handler for GET /agents/list.

handle_list_tools 🔒

Handler for GET /tools/list.

handle_resolve_agent 🔒

Handler for POST /agents/{name}/prompt.

handle_tool_call 🔒

Handler for POST /tools/{name}.

not_found 🔒

Constructs a 404 Not Found error.

run_server

Starts the MCP-compatible HTTP server.

run_server_with_extensions

Starts the MCP server with custom Rust tool and agent extensions.

timeout_error 🔒

Constructs a 408 Request Timeout error.

tool_error 🔒

Constructs a 500 error for tool execution failures.

Type Aliases

ExtState 🔒

Extra extensions (custom Rust tools and agents) passed alongside the main AppState.