Semantica CLI, REST API, and MCP Access Surfaces: A Complete Technical Guide

Semantica exposes its core functionality through three distinct access surfaces: a Click-based Command-Line Interface (CLI), a conventional HTTP REST API, and a JSON-RPC Model Context Protocol (MCP) interface.

The semantica-agi/semantica repository implements these entry points atop a unified execution engine, ensuring consistent behavior whether you invoke operations via terminal commands, HTTP requests, or programmatic RPC calls. Each access surface provides complete coverage of the platform's knowledge graph operations, ingestion pipelines, and decision engines while maintaining synchronized validation schemas.

Command-Line Interface (CLI)

The CLI delivers a rich, typed command hierarchy built on the Click framework. Implemented in semantica/cli.py, this surface defines a command group using @click.group() and nested subcommands such as semantica kg, semantica ingest, and semantica shell.

Click automatically generates help text, validates option types, and raises click.ClickException for user-friendly error reporting. The CLI interfaces directly with the core execution logic, avoiding HTTP serialization overhead for local operations.

# Show top-level help

semantica --help

# Ingest a folder of documents

semantica ingest /path/to/data --store memory

# Export the current graph to GraphML

semantica export_graph --format graphml > graph.graphml

Error handling occurs through Click's exception mechanism. Lines 28-31 in semantica/cli.py demonstrate how the CLI catches and formats exceptions into clean, readable messages before exiting.

REST API

The REST API exposes conventional JSON-over-HTTP endpoints through an HTTP server defined in semantica_mcp/mcp/server.py. This "Explorer" service provides synchronous access to the same internal core used by the CLI.

Key endpoints include POST /api/v1/ingest for document ingestion, GET /api/v1/graph for graph retrieval, and POST /api/v1/decision for decision engine queries. The server authenticates requests, validates payloads against the shared configuration schema, and returns standard HTTP status codes with JSON bodies.

# Ingest JSON documents via HTTP

curl -X POST http://localhost:8000/api/v1/ingest \
     -H "Content-Type: application/json" \
     -d '{"paths": ["data/*.json"]}'

# Retrieve the whole graph in RDF/Turtle

curl http://localhost:8000/api/v1/graph?format=turtle

The validation layer ensures that constraints remain identical across the REST API and CLI surfaces, preventing configuration drift between access methods.

Model Context Protocol (MCP)

The MCP (Model Context Protocol) implements a JSON-RPC-style protocol supporting both STDIO transport for subprocess-based tooling and HTTP transport for network access. Protocol handling resides in semantica_mcp/mcp/__init__.py, while the server entry point in semantica_mcp/mcp/server.py hosts the endpoint.

MCP messages follow a strict JSON structure containing method, params, and id fields. The protocol exposes a catalog of tools—including export_graph, semantic_retrieval, and decision—with individual implementations located in semantica_mcp/mcp/tools/.

from semantica.ingest.mcp_client import MCPClient

# Connect to an MCP server (HTTP or stdio)

client = MCPClient(url="http://localhost:8000/mcp")

# Invoke the `semantic_retrieval` tool

response = client.run_tool(
    "semantic_retrieval",
    {"query": "What are the main components of Semantica?"}
)

print(response["result"])

The MCPClient class serializes requests into JSON-RPC objects, transmits them through the selected transport mechanism, and parses structured JSON responses. This dual-transport capability allows integration with both local subprocesses and remote services.

Shared Core Architecture

All three access surfaces interface with the same underlying execution engine defined in semantica/worker.py. This shared core prevents code duplication and guarantees consistent behavior across terminal, HTTP, and JSON-RPC invocations.

The test suites validate this consistency across surfaces. tests/test_cli_commands.py verifies that CLI commands properly raise click.ClickException, while tests/test_mcp_server_version.py confirms that the MCP server returns correct version metadata.

Summary

• Three entry points serve the Semantica platform: Click-based CLI, HTTP REST API, and JSON-RPC MCP interface.
• CLI implementation in semantica/cli.py leverages Click for command hierarchies, automatic help generation, and type validation.
• REST endpoints defined in semantica_mcp/mcp/server.py provide synchronous HTTP access to ingestion and graph operations.
• MCP protocol supports both STDIO and HTTP transports via semantica_mcp/mcp/server.py, exposing tools like semantic_retrieval and export_graph through JSON-RPC.
• Unified validation ensures identical payload constraints across CLI and REST surfaces, with all routes converging on semantica/worker.py.

Frequently Asked Questions

How does Semantica handle errors differently between the CLI and REST API?

The CLI raises click.ClickException instances that render human-readable messages to stderr, as implemented in semantica/cli.py. The REST API returns standard HTTP status codes with JSON error bodies, while the MCP layer returns JSON-RPC error objects containing structured code and message fields.

Can I use the MCP interface over standard input/output instead of HTTP?

Yes. The MCP implementation in semantica_mcp/mcp/server.py supports STDIO transport for subprocess-based integration, allowing external tools to spawn Semantica as a child process and communicate via stdin/stdout. This mode uses the same JSON-RPC framing as the HTTP variant but eliminates network overhead.

Which access surface should I choose for batch processing large datasets?

For batch processing, use the CLI with commands like semantica ingest for direct filesystem access and local execution through semantica/worker.py. The CLI avoids HTTP serialization overhead and provides progress indicators through Click's echo utilities.

Are the validation schemas identical across all three access surfaces?

Yes. Both the CLI and REST API validate payloads against the same configuration schemas, ensuring that a request valid for semantica ingest will also pass validation when sent to POST /api/v1/ingest. The MCP layer maintains this consistency by routing to the same internal core functions used by the other surfaces.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}