mirror of
https://github.com/semantica-agi/semantica.git
synced 2026-08-29 04:26:20 +00:00
feat(integrations): add OpenClaw plugin and integration module (#460)
- Add integrations/openclaw/ with OpenClawKGTool (REST) and OpenClawMCPConfig (mcporter.json generator) - Add plugins/.openclaw-plugin/ bundle (plugin.json, marketplace.json, README) with MCP + native tool support - Add OpenClaw badge to README header - Reorganize "Works With Every AI Tool" table into labeled groups: Native Plugin Bundle, MCP Server + Plugin, MCP Server, REST API Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Mohd Kaif
co-authored by
Claude Sonnet 4.6
Claude Sonnet 4.6
parent
a1478af9c4
commit
60bf8ec75e
@@ -14,6 +14,7 @@
|
|||||||
[](https://github.com/Hawksight-AI/semantica/actions)
|
[](https://github.com/Hawksight-AI/semantica/actions)
|
||||||
[](https://discord.gg/sV34vps5hH)
|
[](https://discord.gg/sV34vps5hH)
|
||||||
[](https://x.com/BuildSemantica)
|
[](https://x.com/BuildSemantica)
|
||||||
|
[](https://openclaw.ai)
|
||||||
|
|
||||||
### ⭐ Give us a Star · 🍴 Fork us · 💬 Join our Discord · 🐦 Follow on X
|
### ⭐ Give us a Star · 🍴 Fork us · 💬 Join our Discord · 🐦 Follow on X
|
||||||
|
|
||||||
@@ -55,39 +56,68 @@ pip install semantica
|
|||||||
|
|
||||||
## 🔌 Works With Every AI Tool
|
## 🔌 Works With Every AI Tool
|
||||||
|
|
||||||
Semantica ships **native plugin bundles** for Claude Code, Cursor, and Codex, an **MCP server** (`python -m semantica.mcp_server`) for Windsurf, Cline, Continue, VS Code, and Claude Desktop, and a **REST API** (FastAPI, port 8000) for any other tool.
|
Semantica ships **native plugin bundles** for Claude Code, Cursor, and Codex, an **MCP server** (`python -m semantica.mcp_server`) for Windsurf, Cline, Continue, VS Code, Claude Desktop, and OpenClaw, and a **REST API** (FastAPI, port 8000) for any other tool.
|
||||||
|
|
||||||
<table>
|
<table>
|
||||||
|
|
||||||
|
<!-- ── Native Plugin Bundle ──────────────────────────────────────────── -->
|
||||||
|
<tr>
|
||||||
|
<th colspan="3" align="left">🔌 Native Plugin Bundle</th>
|
||||||
|
<th colspan="5" align="left">⚡ MCP Server + Plugin</th>
|
||||||
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td align="center" width="12.5%">
|
<td align="center" width="12.5%">
|
||||||
<a href="https://claude.com/product/claude-code"><img src="https://github.com/anthropics.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
|
<a href="https://claude.com/product/claude-code"><img src="https://github.com/anthropics.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
|
||||||
<strong>Claude Code</strong><br/>
|
<strong>Claude Code</strong><br/>
|
||||||
<sub>Native plugin · 17 skills · 3 agents · hooks</sub>
|
<sub>17 skills · 3 agents · hooks</sub>
|
||||||
</td>
|
</td>
|
||||||
<td align="center" width="12.5%">
|
<td align="center" width="12.5%">
|
||||||
<a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
|
<a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
|
||||||
<strong>Cursor</strong><br/>
|
<strong>Cursor</strong><br/>
|
||||||
<sub>Native plugin · 17 skills · 3 agents</sub>
|
<sub>17 skills · 3 agents</sub>
|
||||||
</td>
|
</td>
|
||||||
<td align="center" width="12.5%">
|
<td align="center" width="12.5%">
|
||||||
<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
|
<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
|
||||||
<strong>Codex CLI</strong><br/>
|
<strong>Codex CLI</strong><br/>
|
||||||
<sub>Native plugin · 17 skills · 3 agents</sub>
|
<sub>17 skills · 3 agents</sub>
|
||||||
</td>
|
</td>
|
||||||
<td align="center" width="12.5%">
|
<td align="center" width="12.5%">
|
||||||
<a href="https://windsurf.com"><img src="https://exafunction.github.io/public/brand/windsurf-black-symbol.svg" alt="Windsurf" width="48" height="48" /></a><br/>
|
<a href="https://windsurf.com"><img src="https://exafunction.github.io/public/brand/windsurf-black-symbol.svg" alt="Windsurf" width="48" height="48" /></a><br/>
|
||||||
<strong>Windsurf</strong><br/>
|
<strong>Windsurf</strong><br/>
|
||||||
<sub>MCP server + plugin</sub>
|
<sub><a href="plugins/.windsurf-plugin/">plugin</a></sub>
|
||||||
</td>
|
</td>
|
||||||
<td align="center" width="12.5%">
|
<td align="center" width="12.5%">
|
||||||
<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
|
<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
|
||||||
<strong>Claude Desktop</strong><br/>
|
<strong>Cline</strong><br/>
|
||||||
<sub>MCP server</sub>
|
<sub><a href="plugins/.cline-plugin/">plugin</a></sub>
|
||||||
|
</td>
|
||||||
|
<td align="center" width="12.5%">
|
||||||
|
<a href="https://github.com/continuedev/continue"><img src="https://github.com/continuedev.png?size=120" alt="Continue" width="48" height="48" /></a><br/>
|
||||||
|
<strong>Continue</strong><br/>
|
||||||
|
<sub><a href="plugins/.continue-plugin/">plugin</a></sub>
|
||||||
</td>
|
</td>
|
||||||
<td align="center" width="12.5%">
|
<td align="center" width="12.5%">
|
||||||
<a href="https://github.com/microsoft/vscode"><img src="https://github.com/microsoft.png?size=120" alt="VS Code" width="48" height="48" /></a><br/>
|
<a href="https://github.com/microsoft/vscode"><img src="https://github.com/microsoft.png?size=120" alt="VS Code" width="48" height="48" /></a><br/>
|
||||||
<strong>VS Code</strong><br/>
|
<strong>VS Code</strong><br/>
|
||||||
<sub>MCP server + plugin</sub>
|
<sub><a href="plugins/.vscode-plugin/">plugin</a></sub>
|
||||||
|
</td>
|
||||||
|
<td align="center" width="12.5%">
|
||||||
|
<a href="integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
|
||||||
|
<strong>OpenClaw</strong><br/>
|
||||||
|
<sub>MCP + <a href="integrations/openclaw/">plugin</a></sub>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
|
||||||
|
<!-- ── MCP Server only · REST API ───────────────────────────────────── -->
|
||||||
|
<tr>
|
||||||
|
<th colspan="1" align="left">☁️ MCP Server</th>
|
||||||
|
<th colspan="7" align="left">🌐 REST API</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td align="center" width="12.5%">
|
||||||
|
<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
|
||||||
|
<strong>Claude Desktop</strong><br/>
|
||||||
|
<sub>MCP server</sub>
|
||||||
</td>
|
</td>
|
||||||
<td align="center" width="12.5%">
|
<td align="center" width="12.5%">
|
||||||
<a href="https://github.com/features/copilot"><img src="https://github.com/github.png?size=120" alt="GitHub Copilot" width="48" height="48" /></a><br/>
|
<a href="https://github.com/features/copilot"><img src="https://github.com/github.png?size=120" alt="GitHub Copilot" width="48" height="48" /></a><br/>
|
||||||
@@ -95,23 +125,11 @@ Semantica ships **native plugin bundles** for Claude Code, Cursor, and Codex, an
|
|||||||
<sub>REST API</sub>
|
<sub>REST API</sub>
|
||||||
</td>
|
</td>
|
||||||
<td align="center" width="12.5%">
|
<td align="center" width="12.5%">
|
||||||
<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
|
|
||||||
<strong>Cline</strong><br/>
|
|
||||||
<sub>MCP server + plugin</sub>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td align="center" width="12.5%">
|
|
||||||
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
|
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
|
||||||
<strong>Roo Code</strong><br/>
|
<strong>Roo Code</strong><br/>
|
||||||
<sub>REST API</sub>
|
<sub>REST API</sub>
|
||||||
</td>
|
</td>
|
||||||
<td align="center" width="12.5%">
|
<td align="center" width="12.5%">
|
||||||
<a href="https://github.com/continuedev/continue"><img src="https://github.com/continuedev.png?size=120" alt="Continue" width="48" height="48" /></a><br/>
|
|
||||||
<strong>Continue</strong><br/>
|
|
||||||
<sub>MCP server + plugin</sub>
|
|
||||||
</td>
|
|
||||||
<td align="center" width="12.5%">
|
|
||||||
<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
|
<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
|
||||||
<strong>Goose</strong><br/>
|
<strong>Goose</strong><br/>
|
||||||
<sub>REST API</sub>
|
<sub>REST API</sub>
|
||||||
@@ -136,12 +154,20 @@ Semantica ships **native plugin bundles** for Claude Code, Cursor, and Codex, an
|
|||||||
<strong>Zed</strong><br/>
|
<strong>Zed</strong><br/>
|
||||||
<sub>REST API</sub>
|
<sub>REST API</sub>
|
||||||
</td>
|
</td>
|
||||||
<td align="center" width="12.5%">
|
</tr>
|
||||||
|
|
||||||
|
<!-- ── Any tool via REST ─────────────────────────────────────────────── -->
|
||||||
|
<tr>
|
||||||
|
<th colspan="8" align="left">🔧 Any Tool</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td align="center" colspan="8">
|
||||||
<img src="https://img.shields.io/badge/109-endpoints-1f6feb?style=flat-square" alt="REST API" width="48" /><br/>
|
<img src="https://img.shields.io/badge/109-endpoints-1f6feb?style=flat-square" alt="REST API" width="48" /><br/>
|
||||||
<strong>Any agent</strong><br/>
|
<strong>Any agent</strong><br/>
|
||||||
<sub>REST API</sub>
|
<sub>109 REST endpoints · FastAPI · port 8000</sub>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
|
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
### Plugin Bundles (Claude Code · Cursor · Codex)
|
### Plugin Bundles (Claude Code · Cursor · Codex)
|
||||||
@@ -157,6 +183,7 @@ Native plugin bundles live under [`plugins/`](plugins/). Each directory contains
|
|||||||
| Cline | [`plugins/.cline-plugin/`](plugins/.cline-plugin/) | 17 skills · 3 agents · MCP config |
|
| Cline | [`plugins/.cline-plugin/`](plugins/.cline-plugin/) | 17 skills · 3 agents · MCP config |
|
||||||
| Continue | [`plugins/.continue-plugin/`](plugins/.continue-plugin/) | 17 skills · 3 agents · MCP config |
|
| Continue | [`plugins/.continue-plugin/`](plugins/.continue-plugin/) | 17 skills · 3 agents · MCP config |
|
||||||
| VS Code | [`plugins/.vscode-plugin/`](plugins/.vscode-plugin/) | 17 skills · 3 agents · MCP config |
|
| VS Code | [`plugins/.vscode-plugin/`](plugins/.vscode-plugin/) | 17 skills · 3 agents · MCP config |
|
||||||
|
| OpenClaw | [`plugins/.openclaw-plugin/`](plugins/.openclaw-plugin/) | 17 skills · 3 agents · MCP config |
|
||||||
|
|
||||||
**17 domain skills:**
|
**17 domain skills:**
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,137 @@
|
|||||||
|
# Semantica × OpenClaw Integration
|
||||||
|
|
||||||
|
Connect [OpenClaw](https://openclaw.ai) — the open-source personal AI agent — to Semantica's full knowledge-graph and decision-intelligence stack.
|
||||||
|
|
||||||
|
Two integration paths are available:
|
||||||
|
|
||||||
|
| Path | When to use |
|
||||||
|
|---|---|
|
||||||
|
| **MCP (recommended)** | OpenClaw Gateway is running; zero extra code needed |
|
||||||
|
| **REST / native tool** | Embedding Semantica directly in a SOUL.md agent config |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Path 1 — MCP Server (recommended)
|
||||||
|
|
||||||
|
### 1. Start the Semantica MCP server
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m semantica.mcp_server
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Add to `mcporter.json`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"semantica": {
|
||||||
|
"command": "python",
|
||||||
|
"args": ["-m", "semantica.mcp_server"],
|
||||||
|
"transport": "stdio"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Restart the OpenClaw Gateway
|
||||||
|
|
||||||
|
```bash
|
||||||
|
openclaw gateway restart
|
||||||
|
```
|
||||||
|
|
||||||
|
All **12 Semantica tools** are now available to any OpenClaw agent:
|
||||||
|
|
||||||
|
| Tool | What it does |
|
||||||
|
|---|---|
|
||||||
|
| `extract_entities` | Named entity recognition from text |
|
||||||
|
| `extract_relations` | Relation / triplet extraction from text |
|
||||||
|
| `record_decision` | Record a decision with causal links |
|
||||||
|
| `query_decisions` | Search recorded decisions |
|
||||||
|
| `find_precedents` | Find past decisions similar to a query |
|
||||||
|
| `get_causal_chain` | Trace cause-effect chains from a node |
|
||||||
|
| `add_entity` | Add a node to the knowledge graph |
|
||||||
|
| `add_relationship` | Add an edge between two nodes |
|
||||||
|
| `run_reasoning` | Forward-chain rules over facts |
|
||||||
|
| `get_graph_analytics` | Centrality, communities, topology stats |
|
||||||
|
| `export_graph` | Export graph (JSON, RDF, GraphML, …) |
|
||||||
|
| `get_graph_summary` | High-level graph overview |
|
||||||
|
|
||||||
|
**3 resources** are also exposed: `semantica://graph/summary`, `semantica://decisions/list`, `semantica://schema/info`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Path 2 — Native Tool (REST)
|
||||||
|
|
||||||
|
Use `OpenClawKGTool` when you prefer a direct Python integration without the MCP gateway.
|
||||||
|
|
||||||
|
### Install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install semantica[openclaw] # pulls in 'requests'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Quick start
|
||||||
|
|
||||||
|
```python
|
||||||
|
from integrations.openclaw import OpenClawKGTool
|
||||||
|
|
||||||
|
tool = OpenClawKGTool(base_url="http://localhost:8000")
|
||||||
|
|
||||||
|
# Extract knowledge from text
|
||||||
|
entities = tool.extract_entities("OpenClaw is an open-source AI agent built in Python.")
|
||||||
|
relations = tool.extract_relations("Alice manages the OpenClaw project at Hawksight.")
|
||||||
|
|
||||||
|
# Record and query decisions
|
||||||
|
tool.record_decision("Deploy model v2 to production", context="latency improved by 40%")
|
||||||
|
precedents = tool.find_precedents("roll back production deployment")
|
||||||
|
|
||||||
|
# Graph analytics
|
||||||
|
summary = tool.get_graph_summary()
|
||||||
|
analytics = tool.get_graph_analytics()
|
||||||
|
|
||||||
|
# Export
|
||||||
|
ttl = tool.export_graph(fmt="ttl")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Generate `mcporter.json` programmatically
|
||||||
|
|
||||||
|
```python
|
||||||
|
from integrations.openclaw import OpenClawMCPConfig
|
||||||
|
|
||||||
|
cfg = OpenClawMCPConfig()
|
||||||
|
print(cfg.to_json()) # → paste into mcporter.json
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## SOUL.md agent snippet
|
||||||
|
|
||||||
|
Add Semantica to any OpenClaw agent by referencing the tool in your `SOUL.md`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Tools
|
||||||
|
|
||||||
|
- name: semantica_kg
|
||||||
|
description: >
|
||||||
|
Semantica knowledge-graph tool. Supports entity extraction, decision
|
||||||
|
recording, graph querying, causal chain analysis, reasoning, and
|
||||||
|
multi-format export.
|
||||||
|
endpoint: http://localhost:8000
|
||||||
|
auth: none
|
||||||
|
|
||||||
|
## Instructions
|
||||||
|
|
||||||
|
You have access to `semantica_kg`. Use it to:
|
||||||
|
- Extract entities and relations from any text the user provides.
|
||||||
|
- Record important decisions and retrieve precedents before recommending actions.
|
||||||
|
- Run graph analytics and export results when the user asks for a summary.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Python 3.8+
|
||||||
|
- `pip install semantica` (core)
|
||||||
|
- `pip install semantica[openclaw]` (adds `requests` for the REST path)
|
||||||
|
- OpenClaw ≥ latest — [openclaw.ai](https://openclaw.ai)
|
||||||
@@ -0,0 +1,57 @@
|
|||||||
|
"""
|
||||||
|
Semantica × OpenClaw Integration
|
||||||
|
==================================
|
||||||
|
|
||||||
|
First-class integration between the Semantica semantic intelligence stack and
|
||||||
|
`OpenClaw <https://openclaw.ai>`_ — the open-source personal AI agent platform.
|
||||||
|
|
||||||
|
OpenClaw connects to external tools via MCP (Model Context Protocol). This
|
||||||
|
integration exposes the full Semantica MCP surface (12 tools, 3 resources) to
|
||||||
|
any OpenClaw agent and also ships a lightweight ``OpenClawKGTool`` that can be
|
||||||
|
dropped directly into an OpenClaw SOUL.md tool-list as a native tool.
|
||||||
|
|
||||||
|
Public surface
|
||||||
|
--------------
|
||||||
|
OpenClawKGTool — Thin wrapper around the Semantica REST API usable as an
|
||||||
|
OpenClaw native tool (no MCP gateway required)
|
||||||
|
OpenClawMCPConfig — Helper that emits the ``mcporter.json`` snippet needed to
|
||||||
|
wire Semantica's MCP server into an OpenClaw gateway
|
||||||
|
|
||||||
|
Quick start
|
||||||
|
-----------
|
||||||
|
pip install semantica
|
||||||
|
|
||||||
|
>>> from integrations.openclaw import OpenClawKGTool, OpenClawMCPConfig
|
||||||
|
>>> print(OpenClawMCPConfig().to_json()) # paste into mcporter.json
|
||||||
|
>>> tool = OpenClawKGTool(base_url="http://localhost:8000")
|
||||||
|
>>> result = tool.extract("OpenClaw is an open-source AI agent framework.")
|
||||||
|
|
||||||
|
MCP quick start
|
||||||
|
---------------
|
||||||
|
Run the Semantica MCP server once::
|
||||||
|
|
||||||
|
python -m semantica.mcp_server
|
||||||
|
|
||||||
|
Then add the printed config snippet to your OpenClaw ``mcporter.json`` and
|
||||||
|
restart the OpenClaw Gateway::
|
||||||
|
|
||||||
|
openclaw gateway restart
|
||||||
|
|
||||||
|
All 12 Semantica tools are then available as native OpenClaw agent tools.
|
||||||
|
|
||||||
|
Compatibility
|
||||||
|
-------------
|
||||||
|
Requires ``semantica >= 0.3.0``. The MCP path requires ``python >= 3.8`` and
|
||||||
|
a running ``semantica.mcp_server`` instance. The REST path requires a running
|
||||||
|
``semantica.server`` instance (``python -m semantica.server``, port 8000 by
|
||||||
|
default).
|
||||||
|
"""
|
||||||
|
|
||||||
|
from .mcp_tool import OpenClawKGTool, OpenClawMCPConfig
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
"OpenClawKGTool",
|
||||||
|
"OpenClawMCPConfig",
|
||||||
|
]
|
||||||
|
|
||||||
|
__version__ = "0.1.0"
|
||||||
@@ -0,0 +1,253 @@
|
|||||||
|
"""
|
||||||
|
OpenClaw ↔ Semantica bridge
|
||||||
|
============================
|
||||||
|
|
||||||
|
Two integration paths:
|
||||||
|
|
||||||
|
1. **MCP (recommended)** — ``OpenClawMCPConfig`` emits the ``mcporter.json``
|
||||||
|
snippet that wires Semantica's MCP server into the OpenClaw Gateway.
|
||||||
|
All 12 Semantica MCP tools become native OpenClaw agent tools with no
|
||||||
|
extra code.
|
||||||
|
|
||||||
|
2. **REST** — ``OpenClawKGTool`` is a plain Python class that calls the
|
||||||
|
Semantica REST API (port 8000) and can be registered as an OpenClaw
|
||||||
|
native tool via SOUL.md ``tools:`` entries.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import json
|
||||||
|
from typing import Any, Dict, List, Optional
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# MCP config helper
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
class OpenClawMCPConfig:
|
||||||
|
"""
|
||||||
|
Generates the ``mcporter.json`` entry needed to connect Semantica's MCP
|
||||||
|
server to the OpenClaw Gateway.
|
||||||
|
|
||||||
|
Parameters
|
||||||
|
----------
|
||||||
|
server_command:
|
||||||
|
Shell command used to launch the Semantica MCP server.
|
||||||
|
Defaults to ``"python -m semantica.mcp_server"``.
|
||||||
|
transport:
|
||||||
|
MCP transport protocol. OpenClaw supports ``"stdio"`` (default)
|
||||||
|
and ``"sse"``.
|
||||||
|
name:
|
||||||
|
Key used in ``mcporter.json``. Defaults to ``"semantica"``.
|
||||||
|
|
||||||
|
Example
|
||||||
|
-------
|
||||||
|
>>> cfg = OpenClawMCPConfig()
|
||||||
|
>>> print(cfg.to_json())
|
||||||
|
# → paste into ~/.openclaw/mcporter.json, then:
|
||||||
|
# → openclaw gateway restart
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
server_command: str = "python -m semantica.mcp_server",
|
||||||
|
transport: str = "stdio",
|
||||||
|
name: str = "semantica",
|
||||||
|
) -> None:
|
||||||
|
self.server_command = server_command
|
||||||
|
self.transport = transport
|
||||||
|
self.name = name
|
||||||
|
|
||||||
|
def to_dict(self) -> Dict[str, Any]:
|
||||||
|
"""Return the config as a plain dict."""
|
||||||
|
parts = self.server_command.split()
|
||||||
|
return {
|
||||||
|
"mcpServers": {
|
||||||
|
self.name: {
|
||||||
|
"command": parts[0],
|
||||||
|
"args": parts[1:],
|
||||||
|
"transport": self.transport,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
def to_json(self, indent: int = 2) -> str:
|
||||||
|
"""Return the config as a JSON string."""
|
||||||
|
return json.dumps(self.to_dict(), indent=indent)
|
||||||
|
|
||||||
|
def __repr__(self) -> str: # pragma: no cover
|
||||||
|
return f"OpenClawMCPConfig(name={self.name!r}, transport={self.transport!r})"
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# REST-based native tool
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
class OpenClawKGTool:
|
||||||
|
"""
|
||||||
|
A Semantica knowledge-graph tool callable from an OpenClaw agent.
|
||||||
|
|
||||||
|
Wraps the Semantica REST API so that an OpenClaw agent configured with
|
||||||
|
this tool (via SOUL.md ``tools:`` entries or programmatic registration)
|
||||||
|
can extract entities, record decisions, query the graph, and more —
|
||||||
|
without requiring the MCP gateway.
|
||||||
|
|
||||||
|
Parameters
|
||||||
|
----------
|
||||||
|
base_url:
|
||||||
|
Base URL of the running Semantica REST server.
|
||||||
|
Defaults to ``"http://localhost:8000"``.
|
||||||
|
timeout:
|
||||||
|
Request timeout in seconds. Defaults to ``30``.
|
||||||
|
|
||||||
|
Notes
|
||||||
|
-----
|
||||||
|
``requests`` is used for HTTP calls. It is listed as an optional
|
||||||
|
dependency under ``semantica[openclaw]``; install it with::
|
||||||
|
|
||||||
|
pip install semantica[openclaw]
|
||||||
|
"""
|
||||||
|
|
||||||
|
TOOL_NAME = "semantica_kg"
|
||||||
|
TOOL_DESCRIPTION = (
|
||||||
|
"Semantica knowledge-graph tool. "
|
||||||
|
"Supports entity extraction, decision recording, graph querying, "
|
||||||
|
"causal chain analysis, reasoning, and multi-format export."
|
||||||
|
)
|
||||||
|
|
||||||
|
def __init__(self, base_url: str = "http://localhost:8000", timeout: int = 30) -> None:
|
||||||
|
self.base_url = base_url.rstrip("/")
|
||||||
|
self.timeout = timeout
|
||||||
|
self._session: Any = None
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Internal helpers
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def _get_session(self) -> Any:
|
||||||
|
if self._session is None:
|
||||||
|
try:
|
||||||
|
import requests
|
||||||
|
self._session = requests.Session()
|
||||||
|
except ImportError as exc:
|
||||||
|
raise ImportError(
|
||||||
|
"The 'requests' package is required for OpenClawKGTool. "
|
||||||
|
"Install it with: pip install semantica[openclaw]"
|
||||||
|
) from exc
|
||||||
|
return self._session
|
||||||
|
|
||||||
|
def _post(self, endpoint: str, payload: Dict[str, Any]) -> Dict[str, Any]:
|
||||||
|
session = self._get_session()
|
||||||
|
url = f"{self.base_url}{endpoint}"
|
||||||
|
response = session.post(url, json=payload, timeout=self.timeout)
|
||||||
|
response.raise_for_status()
|
||||||
|
return response.json()
|
||||||
|
|
||||||
|
def _get(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
||||||
|
session = self._get_session()
|
||||||
|
url = f"{self.base_url}{endpoint}"
|
||||||
|
response = session.get(url, params=params or {}, timeout=self.timeout)
|
||||||
|
response.raise_for_status()
|
||||||
|
return response.json()
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Extraction
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def extract(self, text: str) -> Dict[str, Any]:
|
||||||
|
"""Extract entities and relations from *text*."""
|
||||||
|
return self._post("/extract", {"text": text})
|
||||||
|
|
||||||
|
def extract_entities(self, text: str) -> List[Dict[str, Any]]:
|
||||||
|
"""Return only the entity list from *text*."""
|
||||||
|
result = self.extract(text)
|
||||||
|
return result.get("entities", [])
|
||||||
|
|
||||||
|
def extract_relations(self, text: str) -> List[Dict[str, Any]]:
|
||||||
|
"""Return only the relation list from *text*."""
|
||||||
|
result = self.extract(text)
|
||||||
|
return result.get("relations", [])
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Graph mutation
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def add_entity(self, label: str, entity_type: str = "Entity", **properties: Any) -> Dict[str, Any]:
|
||||||
|
"""Add a node to the knowledge graph."""
|
||||||
|
return self._post("/entities", {"label": label, "type": entity_type, **properties})
|
||||||
|
|
||||||
|
def add_relationship(
|
||||||
|
self,
|
||||||
|
source: str,
|
||||||
|
target: str,
|
||||||
|
relation_type: str,
|
||||||
|
**properties: Any,
|
||||||
|
) -> Dict[str, Any]:
|
||||||
|
"""Add an edge between *source* and *target*."""
|
||||||
|
return self._post(
|
||||||
|
"/relationships",
|
||||||
|
{"source": source, "target": target, "type": relation_type, **properties},
|
||||||
|
)
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Decisions
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def record_decision(
|
||||||
|
self,
|
||||||
|
decision_text: str,
|
||||||
|
context: Optional[str] = None,
|
||||||
|
**metadata: Any,
|
||||||
|
) -> Dict[str, Any]:
|
||||||
|
"""Record a decision in the graph."""
|
||||||
|
payload: Dict[str, Any] = {"decision": decision_text}
|
||||||
|
if context:
|
||||||
|
payload["context"] = context
|
||||||
|
payload.update(metadata)
|
||||||
|
return self._post("/decisions", payload)
|
||||||
|
|
||||||
|
def query_decisions(self, query: str, limit: int = 10) -> List[Dict[str, Any]]:
|
||||||
|
"""Search recorded decisions."""
|
||||||
|
result = self._get("/decisions/search", {"q": query, "limit": limit})
|
||||||
|
return result.get("decisions", [])
|
||||||
|
|
||||||
|
def find_precedents(self, decision_text: str, top_k: int = 5) -> List[Dict[str, Any]]:
|
||||||
|
"""Find past decisions similar to *decision_text*."""
|
||||||
|
result = self._post("/decisions/precedents", {"decision": decision_text, "top_k": top_k})
|
||||||
|
return result.get("precedents", [])
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Analytics & reasoning
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def get_causal_chain(self, node_id: str, depth: int = 3) -> Dict[str, Any]:
|
||||||
|
"""Retrieve the causal chain rooted at *node_id*."""
|
||||||
|
return self._get("/causal-chain", {"node_id": node_id, "depth": depth})
|
||||||
|
|
||||||
|
def run_reasoning(self, rules: List[str], facts: List[str]) -> Dict[str, Any]:
|
||||||
|
"""Run the Semantica forward-chaining reasoner."""
|
||||||
|
return self._post("/reason", {"rules": rules, "facts": facts})
|
||||||
|
|
||||||
|
def get_graph_analytics(self) -> Dict[str, Any]:
|
||||||
|
"""Return graph-level analytics (centrality, communities, etc.)."""
|
||||||
|
return self._get("/analytics")
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Export
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def export_graph(self, fmt: str = "json") -> str:
|
||||||
|
"""Export the graph in *fmt* (``json``, ``ttl``, ``graphml``, …)."""
|
||||||
|
result = self._get("/export", {"format": fmt})
|
||||||
|
return result.get("data", "")
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# Summary
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def get_graph_summary(self) -> Dict[str, Any]:
|
||||||
|
"""Return a high-level summary of the current graph."""
|
||||||
|
return self._get("/graph/summary")
|
||||||
|
|
||||||
|
def __repr__(self) -> str: # pragma: no cover
|
||||||
|
return f"OpenClawKGTool(base_url={self.base_url!r})"
|
||||||
@@ -0,0 +1,62 @@
|
|||||||
|
# Semantica — OpenClaw Plugin
|
||||||
|
|
||||||
|
Adds all 17 Semantica skills, 3 agents, and the full MCP integration to [OpenClaw](https://openclaw.ai) — the open-source personal AI agent platform.
|
||||||
|
|
||||||
|
## MCP Server Setup (recommended)
|
||||||
|
|
||||||
|
### 1. Start the Semantica MCP server
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m semantica.mcp_server
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Add to `mcporter.json`
|
||||||
|
|
||||||
|
Paste the following into your OpenClaw `mcporter.json` (usually `~/.openclaw/mcporter.json`):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"semantica": {
|
||||||
|
"command": "python",
|
||||||
|
"args": ["-m", "semantica.mcp_server"],
|
||||||
|
"transport": "stdio"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Restart the OpenClaw Gateway
|
||||||
|
|
||||||
|
```bash
|
||||||
|
openclaw gateway restart
|
||||||
|
```
|
||||||
|
|
||||||
|
OpenClaw will automatically discover all 12 Semantica tools and 3 resources.
|
||||||
|
|
||||||
|
## Skills
|
||||||
|
|
||||||
|
All 17 skills under [`plugins/skills/`](../skills/) are available once the plugin is loaded:
|
||||||
|
|
||||||
|
`extract` · `ingest` · `query` · `ontology` · `validate` · `deduplicate` · `embed` · `reason` · `decision` · `causal` · `temporal` · `provenance` · `policy` · `explain` · `export` · `change` · `visualize`
|
||||||
|
|
||||||
|
## Native Tool (REST, no MCP gateway)
|
||||||
|
|
||||||
|
For agents that cannot use the MCP gateway, use the `OpenClawKGTool` REST wrapper:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from integrations.openclaw import OpenClawKGTool
|
||||||
|
|
||||||
|
tool = OpenClawKGTool(base_url="http://localhost:8000")
|
||||||
|
entities = tool.extract_entities("Alice manages the project.")
|
||||||
|
tool.record_decision("Deploy model v2 to production")
|
||||||
|
summary = tool.get_graph_summary()
|
||||||
|
```
|
||||||
|
|
||||||
|
See [`integrations/openclaw/README.md`](../../integrations/openclaw/README.md) for the full guide, including SOUL.md agent snippets.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Python 3.8+
|
||||||
|
- `pip install semantica`
|
||||||
|
- OpenClaw — [openclaw.ai](https://openclaw.ai)
|
||||||
@@ -0,0 +1,18 @@
|
|||||||
|
{
|
||||||
|
"name": "semantica-openclaw",
|
||||||
|
"plugins": [
|
||||||
|
{
|
||||||
|
"name": "semantica",
|
||||||
|
"description": "Semantica plugin for OpenClaw: knowledge graph skills, decision intelligence, reasoning, extraction, and visualization.",
|
||||||
|
"source": "./",
|
||||||
|
"category": "Productivity",
|
||||||
|
"tags": [
|
||||||
|
"knowledge-graph",
|
||||||
|
"reasoning",
|
||||||
|
"semantica",
|
||||||
|
"openclaw",
|
||||||
|
"mcp"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
@@ -0,0 +1,46 @@
|
|||||||
|
{
|
||||||
|
"name": "semantica-openclaw",
|
||||||
|
"displayName": "Semantica OpenClaw Plugin",
|
||||||
|
"description": "Semantica plugin for OpenClaw: knowledge graph skills, decision intelligence, reasoning, extraction, and visualization via MCP and native REST tool.",
|
||||||
|
"version": "0.1.0",
|
||||||
|
"author": {
|
||||||
|
"name": "Semantica Contributors"
|
||||||
|
},
|
||||||
|
"homepage": "https://github.com/Hawksight-AI/semantica",
|
||||||
|
"repository": "https://github.com/Hawksight-AI/semantica",
|
||||||
|
"license": "MIT",
|
||||||
|
"keywords": [
|
||||||
|
"semantica",
|
||||||
|
"knowledge graph",
|
||||||
|
"openclaw",
|
||||||
|
"context graphs",
|
||||||
|
"decision intelligence",
|
||||||
|
"explainability",
|
||||||
|
"causal analysis",
|
||||||
|
"provenance",
|
||||||
|
"ontology",
|
||||||
|
"graph analytics",
|
||||||
|
"semantic extraction",
|
||||||
|
"visualization",
|
||||||
|
"reasoning",
|
||||||
|
"mcp"
|
||||||
|
],
|
||||||
|
"skills": "../skills",
|
||||||
|
"agents": "../agents",
|
||||||
|
"hooks": "../hooks/hooks.json",
|
||||||
|
"mcp": {
|
||||||
|
"server": "python -m semantica.mcp_server",
|
||||||
|
"transport": "stdio"
|
||||||
|
},
|
||||||
|
"openclaw": {
|
||||||
|
"mcporter": {
|
||||||
|
"mcpServers": {
|
||||||
|
"semantica": {
|
||||||
|
"command": "python",
|
||||||
|
"args": ["-m", "semantica.mcp_server"],
|
||||||
|
"transport": "stdio"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user