7.3 KiB
title, description, icon
| title | description | icon |
|---|---|---|
| MCP Server | Model Context Protocol server — expose Semantica's full capability set to Claude Desktop, VS Code, Cursor, and any MCP-aware tool. | plug |
semantica.mcp_server exposes Semantica's knowledge graph, decision intelligence, semantic extraction, and reasoning capabilities as an MCP (Model Context Protocol) server over stdio.
Compatible with Claude Desktop, Windsurf, Cline, Continue, VS Code, Roo Code, Cursor, and any MCP-aware client.
What You Get
- 12 MCP tools — extract entities, build graphs, run SPARQL, find paths, get recommendations, embed, cluster, and more
- 3 readable resources — live graph JSON, entity list, and relationship list
- Zero infrastructure — runs over stdio, no server or port needed
- Claude Desktop ready — one config block to add to
claude_desktop_config.json - REST alternative — the Explorer module offers a full HTTP API if you prefer
Installation
pip install semantica
The MCP server is included in the base install — no extras required.
Configuration
Add Semantica to your MCP client's settings file:
{
"mcpServers": {
"semantica": {
"command": "semantica-mcp"
}
}
}
{
"mcpServers": {
"semantica": {
"command": "python",
"args": ["-m", "semantica.mcp_server"]
}
}
}
{
"mcpServers": {
"semantica": {
"command": "semantica-mcp",
"env": {
"SEMANTICA_KG_PATH": "/path/to/my_graph.json",
"SEMANTICA_LOG_LEVEL": "INFO"
}
}
}
}
Environment Variables
| Variable | Default | Description |
|---|---|---|
SEMANTICA_KG_PATH |
(none) | Path to a persisted graph to load on startup |
SEMANTICA_LOG_LEVEL |
WARNING |
Log verbosity: DEBUG, INFO, WARNING |
Tools
The MCP server exposes 12 tools that any connected AI assistant can call:
Knowledge Extraction
Extract named entities (people, places, organisations, concepts) from text using Semantica NER.
Input:
{ "text": "Apple Inc. was founded by Steve Jobs in Cupertino in 1976." }
Output:
{
"entities": [
{ "label": "Apple Inc.", "type": "ORGANIZATION", "start": 0, "end": 10 },
{ "label": "Steve Jobs", "type": "PERSON", "start": 26, "end": 36 },
{ "label": "Cupertino", "type": "LOCATION", "start": 40, "end": 49 },
{ "label": "1976", "type": "DATE", "start": 53, "end": 57 }
]
}
Extract typed relations and (subject, predicate, object) triplets from text.
Input:
{ "text": "Steve Jobs founded Apple Inc. and led it until 2011." }
Output:
{
"relations": [
{ "source": "Steve Jobs", "type": "founded", "target": "Apple Inc." }
],
"triplets": [
{ "subject": "Steve Jobs", "predicate": "founded", "object": "Apple Inc." }
]
}
Decision Intelligence
Record a decision with full context, reasoning, and metadata into the knowledge graph.
Input:
{
"category": "model_selection",
"scenario": "Choose LLM for production reasoning pipeline",
"reasoning": "GPT-4 benchmark advantage justifies 3x cost increase",
"outcome": "selected_gpt4",
"confidence": 0.91,
"decision_maker": "product_team"
}
Output:
{ "decision_id": "dec_a1b2c3", "status": "recorded" }
Query recorded decisions by natural language, category, or retrieve all recent decisions.
Input:
{ "query": "model selection", "limit": 5 }
Find past decisions similar to a given scenario using hybrid similarity search.
Input:
{ "scenario": "Choose cloud provider for HIPAA workload", "max_results": 3 }
Trace the causal chain upstream or downstream from a decision.
Input:
{ "decision_id": "dec_a1b2c3", "direction": "downstream", "max_depth": 5 }
Graph Operations
Add a node/entity to the live knowledge graph.
Input:
{
"id": "apple_inc",
"label": "Apple Inc.",
"type": "Organization",
"metadata": { "founded": 1976, "hq": "Cupertino" }
}
Add a directed relationship (edge) between two existing entities.
Input:
{
"source": "steve_jobs",
"target": "apple_inc",
"type": "FOUNDED",
"metadata": { "year": 1976 }
}
Compute PageRank centrality and community detection over the current graph. Returns top nodes by influence and community count.
Return node count, decision count, and graph health status.
Reasoning & Export
Run forward-chaining IF/THEN rules over a set of facts to derive new facts.
Input:
{
"facts": ["Employee(John)", "Manager(John)"],
"rules": ["IF Manager(?x) THEN HasAuthority(?x)"]
}
Output:
{ "derived_facts": ["HasAuthority(John)"] }
Export the current knowledge graph to a serialization format.
Input:
{ "format": "json-ld" }
Supported formats: turtle, ttl, nt, xml, json-ld, json.
Resources
The MCP server also exposes three readable resources:
| URI | Description |
|---|---|
semantica://graph/summary |
High-level graph statistics |
semantica://decisions/list |
All recorded decisions (up to 50) |
semantica://schema/info |
Server version and available tools |
Test Locally
# Run the server directly (reads from stdin, writes to stdout)
semantica-mcp
# Or via Python module
python -m semantica.mcp_server
Send a JSON-RPC initialize message to confirm it's working:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | semantica-mcp