semantica/mcp

Semantica MCP Server

A fully modular Model Context Protocol server for the Semantica knowledge graph.
Connects Claude Code, Cursor, Windsurf, Cline, Continue, VS Code (GitHub Copilot), and any other MCP-compatible AI tool directly to your Semantica graph.

---

Quick start

# From the repo root
pip install -e ".[mcp]"

# Test the server (type a JSON-RPC request, press Enter)
python -m mcp

Or point your AI tool at it (see per-tool configs below).

---

Transport

stdio — the server reads newline-delimited JSON-RPC 2.0 from stdin and writes responses to stdout.
Log/debug output goes to stderr only.

python -m mcp [--debug]

---

Tools (17 total)

Extraction

Tool	Description
extract_entities	Named entity recognition (NER) — people, places, orgs, concepts
extract_relations	Relation extraction + (subject, predicate, object) triplets
extract_all	Full pipeline: NER + coreference + relations + events + triplets

Decision Intelligence

Tool	Description
record_decision	Record a decision with context, confidence, causal links
query_decisions	Query decisions by natural language or structured filters
find_precedents	Find past decisions similar to a scenario (hybrid similarity)
get_causal_chain	Trace upstream/downstream causal chain from a decision
analyze_decision_impact	Analyse downstream influence of a decision

Knowledge Graph

Tool	Description
add_entity	Add a node/entity to the graph
add_relationship	Add a directed edge between two entities
search_graph	Search nodes by label or ID substring
get_graph_summary	Node/edge counts, decision count, type breakdown
get_graph_analytics	PageRank, betweenness, degree centrality, community detection

Reasoning

Tool	Description
run_reasoning	Forward-chaining IF/THEN rules over facts
abductive_reasoning	Generate plausible hypotheses for observations

Export & Provenance

Tool	Description
export_graph	Export graph to JSON, CSV, GraphML, Parquet, Turtle, N-Triples, RDF/XML, JSON-LD
get_provenance	Audit history and source lineage for a node

---

Resources (4 total)

URI	Description
semantica://graph/summary	Live node/edge counts and type breakdown
semantica://decisions/list	Most recent 50 decisions
semantica://schema/info	Schema version, node/edge types, tool names
semantica://ontology/schema	Full ontology schema

---

Per-tool configuration

Claude Code (~/.claude/settings.json)

{
  "mcpServers": {
    "semantica": {
      "command": "python",
      "args": ["-m", "mcp"],
      "cwd": "/path/to/semantica"
    }
  }
}

Or use the plugin bundle:

claude mcp add semantica python -m mcp --cwd /path/to/semantica

---

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "semantica": {
      "command": "python",
      "args": ["-m", "mcp"],
      "cwd": "/path/to/semantica"
    }
  }
}

---

Windsurf (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "semantica": {
      "command": "python",
      "args": ["-m", "mcp"],
      "cwd": "/path/to/semantica"
    }
  }
}

---

Cline (VS Code extension settings)

In your VS Code settings.json:

{
  "cline.mcpServers": {
    "semantica": {
      "command": "python",
      "args": ["-m", "mcp"],
      "cwd": "/path/to/semantica"
    }
  }
}

---

Continue (~/.continue/config.json)

{
  "mcpServers": [
    {
      "name": "semantica",
      "command": "python",
      "args": ["-m", "mcp"],
      "cwd": "/path/to/semantica"
    }
  ]
}

---

VS Code (GitHub Copilot) — .vscode/mcp.json

{
  "servers": {
    "semantica": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

---

Amazon Q Developer

Add to your Q Developer MCP config:

{
  "mcpServers": {
    "semantica": {
      "command": "python",
      "args": ["-m", "mcp"],
      "cwd": "/path/to/semantica"
    }
  }
}

---

Environment variables

Variable	Default	Description
SEMANTICA_KG_PATH	(in-memory)	Path to persist/load the graph (JSON file)

---

Package structure

mcp/
├── __init__.py          # Package entry, re-exports SemanticaMCPServer + main
├── __main__.py          # python -m mcp entry point
├── server.py            # SemanticaMCPServer class + stdio event loop
├── session.py           # Lazy ContextGraph singleton (get_graph / reset_graph)
├── schemas.py           # JSON Schema definitions for all tool inputs
├── tools/
│   ├── __init__.py      # Assembles TOOL_DEFINITIONS list
│   ├── extraction.py    # NER, relation extraction, full pipeline
│   ├── decisions.py     # Record, query, precedents, causal chain, impact
│   ├── graph.py         # Add entity/relationship, search, summary, analytics
│   ├── reasoning.py     # Forward-chaining rules, abductive hypotheses
│   └── export.py        # Graph export (multi-format) + provenance
└── resources/
    ├── __init__.py      # Re-exports RESOURCE_DEFINITIONS + handle_resource_read
    └── registry.py      # URI → handler map for the 4 semantica:// resources