neruva-mcp 0.1.0__tar.gz

neruva_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clouthier Simulation Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neruva_mcp-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+recursive-include src *.py
+include src/neruva_mcp/py.typed
+global-exclude __pycache__
+global-exclude *.pyc
+global-exclude .DS_Store
+prune tests
+prune .git

neruva_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: neruva-mcp
+Version: 0.1.0
+Summary: Model Context Protocol server for Neruva — vector memory + HD-native substrate (KGs, analogy, causal do-operator, EFE planning).
+Author-email: Clouthier Simulation Labs <info@neruva.io>
+License: MIT
+Project-URL: Homepage, https://neruva.io/integrations/
+Project-URL: Documentation, https://neruva.io/docs/
+Project-URL: Source, https://github.com/CloutSimLabs/neruva
+Keywords: mcp,model-context-protocol,neruva,vector-database,agent-memory,knowledge-graph,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: httpx>=0.27
+Dynamic: license-file
+
+# neruva-mcp
+
+Model Context Protocol server for [Neruva](https://neruva.io) — vector memory + HD-native substrate. Same 8 tools as the TypeScript package, for Python-only MCP hosts (e.g. Codex, custom agents).
+
+## Install
+
+```bash
+pip install neruva-mcp
+export NERUVA_API_KEY=...        # from https://app.neruva.io
+```
+
+Or zero-install via `uvx`:
+
+```bash
+uvx neruva-mcp
+```
+
+## Use
+
+Add to your MCP host's config. Example for Claude Code:
+
+```bash
+claude mcp add neruva -- uvx neruva-mcp -e NERUVA_API_KEY=YOUR_KEY
+```
+
+Or run directly:
+
+```bash
+NERUVA_API_KEY=YOUR_KEY neruva-mcp
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `memory_upsert` | Insert/update vectors in a namespace (Pinecone-compatible) |
+| `memory_query`  | Top-K cosine search |
+| `memory_delete` | Delete by id |
+| `hd_kg_add_fact` | Add (subject, relation, object) to a KG |
+| `hd_kg_query` | Query KG for object of (subject, relation) |
+| `hd_analogy` | Four-term analogy in HD feature space |
+| `hd_causal_query` | Observational / interventional query on stored SCM |
+| `hd_plan` | EFE active-inference planner |
+
+## Env
+
+| Variable | Default |
+|---|---|
+| `NERUVA_API_KEY` | required |
+| `NERUVA_URL` | `https://api.neruva.io` |
+
+## License
+
+MIT — Clouthier Simulation Labs.

neruva_mcp-0.1.0/README.md

@@ -0,0 +1,54 @@
+# neruva-mcp
+
+Model Context Protocol server for [Neruva](https://neruva.io) — vector memory + HD-native substrate. Same 8 tools as the TypeScript package, for Python-only MCP hosts (e.g. Codex, custom agents).
+
+## Install
+
+```bash
+pip install neruva-mcp
+export NERUVA_API_KEY=...        # from https://app.neruva.io
+```
+
+Or zero-install via `uvx`:
+
+```bash
+uvx neruva-mcp
+```
+
+## Use
+
+Add to your MCP host's config. Example for Claude Code:
+
+```bash
+claude mcp add neruva -- uvx neruva-mcp -e NERUVA_API_KEY=YOUR_KEY
+```
+
+Or run directly:
+
+```bash
+NERUVA_API_KEY=YOUR_KEY neruva-mcp
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `memory_upsert` | Insert/update vectors in a namespace (Pinecone-compatible) |
+| `memory_query`  | Top-K cosine search |
+| `memory_delete` | Delete by id |
+| `hd_kg_add_fact` | Add (subject, relation, object) to a KG |
+| `hd_kg_query` | Query KG for object of (subject, relation) |
+| `hd_analogy` | Four-term analogy in HD feature space |
+| `hd_causal_query` | Observational / interventional query on stored SCM |
+| `hd_plan` | EFE active-inference planner |
+
+## Env
+
+| Variable | Default |
+|---|---|
+| `NERUVA_API_KEY` | required |
+| `NERUVA_URL` | `https://api.neruva.io` |
+
+## License
+
+MIT — Clouthier Simulation Labs.

neruva_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "neruva-mcp"
+version = "0.1.0"
+description = "Model Context Protocol server for Neruva — vector memory + HD-native substrate (KGs, analogy, causal do-operator, EFE planning)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Clouthier Simulation Labs", email = "info@neruva.io" },
+]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "neruva",
+    "vector-database",
+    "agent-memory",
+    "knowledge-graph",
+    "ai",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://neruva.io/integrations/"
+Documentation = "https://neruva.io/docs/"
+Source = "https://github.com/CloutSimLabs/neruva"
+
+[project.scripts]
+neruva-mcp = "neruva_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+neruva_mcp = ["py.typed"]

neruva_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

neruva_mcp-0.1.0/src/neruva_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""Neruva MCP server (Python).
+
+Thin stdio Model Context Protocol wrapper over the Neruva REST API.
+"""
+
+__version__ = "0.1.0"

neruva_mcp-0.1.0/src/neruva_mcp/server.py

@@ -0,0 +1,321 @@
+"""Neruva MCP server.
+
+Exposes Neruva Memory + HD Substrate to any MCP-aware host as a small
+set of tools. Pure thin wrapper over the REST API at api.neruva.io --
+this process holds NO algorithmic state and imports nothing from the
+substrate core. The hard work happens server-side; this is just glue.
+
+Env:
+  NERUVA_API_KEY  required, your key from app.neruva.io
+  NERUVA_URL      optional, defaults to https://api.neruva.io
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+API_KEY = os.environ.get("NERUVA_API_KEY")
+BASE_URL = os.environ.get("NERUVA_URL", "https://api.neruva.io").rstrip("/")
+
+
+def _enc(s: str) -> str:
+    return quote(s, safe="")
+
+
+async def _call(
+    client: httpx.AsyncClient,
+    method: str,
+    path: str,
+    body: Any | None = None,
+) -> Any:
+    headers = {"Api-Key": API_KEY or ""}
+    if body is not None:
+        headers["Content-Type"] = "application/json"
+    r = await client.request(method, BASE_URL + path, headers=headers, json=body)
+    if r.status_code >= 400:
+        raise RuntimeError(f"{method} {path} -> {r.status_code}: {r.text}")
+    try:
+        return r.json()
+    except Exception:
+        return r.text
+
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="memory_upsert",
+        description="Insert or update vectors in a Neruva Memory namespace. Pinecone-compatible payload.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "index": {"type": "string", "description": "Index name"},
+                "namespace": {"type": "string", "description": "Namespace (one per agent)"},
+                "vectors": {
+                    "type": "array",
+                    "description": "Vectors: {id, values, metadata?}",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "id": {"type": "string"},
+                            "values": {"type": "array", "items": {"type": "number"}},
+                            "metadata": {"type": "object"},
+                        },
+                        "required": ["id", "values"],
+                    },
+                },
+            },
+            "required": ["index", "namespace", "vectors"],
+        },
+    ),
+    Tool(
+        name="memory_query",
+        description="Cosine-search a namespace by vector. Returns top-K matches with metadata.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "index": {"type": "string"},
+                "namespace": {"type": "string"},
+                "vector": {"type": "array", "items": {"type": "number"}},
+                "topK": {"type": "integer", "default": 10},
+                "includeMetadata": {"type": "boolean", "default": True},
+            },
+            "required": ["index", "namespace", "vector"],
+        },
+    ),
+    Tool(
+        name="memory_delete",
+        description="Delete vectors by id from a namespace.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "index": {"type": "string"},
+                "namespace": {"type": "string"},
+                "ids": {"type": "array", "items": {"type": "string"}},
+            },
+            "required": ["index", "namespace", "ids"],
+        },
+    ),
+    Tool(
+        name="hd_kg_add_fact",
+        description="Add a (subject, relation, object) fact to a knowledge graph. Persists across restarts.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "kg": {"type": "string", "description": "Knowledge-graph name"},
+                "subject": {"type": "string"},
+                "relation": {"type": "string"},
+                "object": {"type": "string"},
+            },
+            "required": ["kg", "subject", "relation", "object"],
+        },
+    ),
+    Tool(
+        name="hd_kg_query",
+        description="Query a knowledge graph for the object of (subject, relation). Returns object + confidence.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "kg": {"type": "string"},
+                "subject": {"type": "string"},
+                "relation": {"type": "string"},
+            },
+            "required": ["kg", "subject", "relation"],
+        },
+    ),
+    Tool(
+        name="hd_analogy",
+        description=(
+            "Solve a four-term analogy in HD feature space: a is to b as c is to ? "
+            "Items are integer feature IDs in [0, 2^n_feat). Returns the cleaned-up "
+            "candidate plus cosine, runner-up cosine, and a confidence gap."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "n_feat": {"type": "integer", "description": "Number of binary features. Item space size is 2^n_feat."},
+                "a": {"type": "integer"},
+                "b": {"type": "integer"},
+                "c": {"type": "integer"},
+                "seed": {"type": "integer", "default": 4301},
+            },
+            "required": ["n_feat", "a", "b", "c"],
+        },
+    ),
+    Tool(
+        name="hd_causal_query",
+        description=(
+            "Run an observational or interventional query against a stored causal model. "
+            "query_type is 'observation' or 'intervention' -- arithmetically distinct."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scm": {"type": "string", "description": "Causal-model name"},
+                "query_type": {"type": "string", "enum": ["observation", "intervention"]},
+                "condition_var": {"type": "integer"},
+                "condition_value": {"type": "integer"},
+                "query_var": {"type": "integer"},
+                "query_value": {"type": "integer"},
+            },
+            "required": [
+                "scm",
+                "query_type",
+                "condition_var",
+                "condition_value",
+                "query_var",
+                "query_value",
+            ],
+        },
+    ),
+    Tool(
+        name="hd_plan",
+        description="Plan a sequence of actions toward a goal using the EFE active-inference planner.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "model": {"type": "string", "description": "Planner-model name"},
+                "start": {"type": "object", "description": "Start state"},
+                "goal": {"type": "object", "description": "Goal state"},
+                "horizon": {"type": "integer", "default": 4},
+            },
+            "required": ["model", "start", "goal"],
+        },
+    ),
+]
+
+
+async def _dispatch(client: httpx.AsyncClient, name: str, args: dict[str, Any]) -> Any:
+    if name == "memory_upsert":
+        return await _call(
+            client,
+            "POST",
+            f"/v1/indexes/{_enc(args['index'])}/namespaces/{_enc(args['namespace'])}/upsert",
+            {"vectors": args["vectors"]},
+        )
+    if name == "memory_query":
+        return await _call(
+            client,
+            "POST",
+            f"/v1/indexes/{_enc(args['index'])}/namespaces/{_enc(args['namespace'])}/query",
+            {
+                "vector": args["vector"],
+                "topK": args.get("topK", 10),
+                "includeMetadata": args.get("includeMetadata", True),
+            },
+        )
+    if name == "memory_delete":
+        return await _call(
+            client,
+            "POST",
+            f"/v1/indexes/{_enc(args['index'])}/namespaces/{_enc(args['namespace'])}/delete",
+            {"ids": args["ids"]},
+        )
+    if name == "hd_kg_add_fact":
+        return await _call(
+            client,
+            "POST",
+            f"/v1/hd/kg/{_enc(args['kg'])}/facts",
+            {
+                "facts": [
+                    {
+                        "subject": args["subject"],
+                        "relation": args["relation"],
+                        "object": args["object"],
+                    }
+                ]
+            },
+        )
+    if name == "hd_kg_query":
+        return await _call(
+            client,
+            "POST",
+            f"/v1/hd/kg/{_enc(args['kg'])}/query",
+            {"subject": args["subject"], "relation": args["relation"]},
+        )
+    if name == "hd_analogy":
+        return await _call(
+            client,
+            "POST",
+            "/v1/hd/analogy",
+            {
+                "n_feat": args["n_feat"],
+                "a": args["a"],
+                "b": args["b"],
+                "c": args["c"],
+                "seed": args.get("seed", 4301),
+            },
+        )
+    if name == "hd_causal_query":
+        return await _call(
+            client,
+            "POST",
+            f"/v1/hd/causal/{_enc(args['scm'])}/query",
+            {
+                "query_type": args["query_type"],
+                "condition_var": args["condition_var"],
+                "condition_value": args["condition_value"],
+                "query_var": args["query_var"],
+                "query_value": args["query_value"],
+            },
+        )
+    if name == "hd_plan":
+        return await _call(
+            client,
+            "POST",
+            f"/v1/hd/plan/{_enc(args['model'])}",
+            {
+                "start": args["start"],
+                "goal": args["goal"],
+                "horizon": args.get("horizon", 4),
+            },
+        )
+    raise ValueError(f"unknown tool: {name}")
+
+
+async def _run() -> None:
+    if not API_KEY:
+        print(
+            "[neruva-mcp] NERUVA_API_KEY not set. Get one at https://app.neruva.io",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    server: Server = Server("neruva")
+
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        return TOOLS
+
+    async with httpx.AsyncClient(timeout=60.0) as client:
+
+        @server.call_tool()
+        async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+            try:
+                result = await _dispatch(client, name, arguments or {})
+                return [TextContent(type="text", text=json.dumps(result, indent=2))]
+            except Exception as e:
+                return [TextContent(type="text", text=f"error: {e}")]
+
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                server.create_initialization_options(),
+            )
+
+
+def main() -> None:
+    asyncio.run(_run())
+
+
+if __name__ == "__main__":
+    main()

neruva_mcp-0.1.0/src/neruva_mcp.egg-info/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: neruva-mcp
+Version: 0.1.0
+Summary: Model Context Protocol server for Neruva — vector memory + HD-native substrate (KGs, analogy, causal do-operator, EFE planning).
+Author-email: Clouthier Simulation Labs <info@neruva.io>
+License: MIT
+Project-URL: Homepage, https://neruva.io/integrations/
+Project-URL: Documentation, https://neruva.io/docs/
+Project-URL: Source, https://github.com/CloutSimLabs/neruva
+Keywords: mcp,model-context-protocol,neruva,vector-database,agent-memory,knowledge-graph,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: httpx>=0.27
+Dynamic: license-file
+
+# neruva-mcp
+
+Model Context Protocol server for [Neruva](https://neruva.io) — vector memory + HD-native substrate. Same 8 tools as the TypeScript package, for Python-only MCP hosts (e.g. Codex, custom agents).
+
+## Install
+
+```bash
+pip install neruva-mcp
+export NERUVA_API_KEY=...        # from https://app.neruva.io
+```
+
+Or zero-install via `uvx`:
+
+```bash
+uvx neruva-mcp
+```
+
+## Use
+
+Add to your MCP host's config. Example for Claude Code:
+
+```bash
+claude mcp add neruva -- uvx neruva-mcp -e NERUVA_API_KEY=YOUR_KEY
+```
+
+Or run directly:
+
+```bash
+NERUVA_API_KEY=YOUR_KEY neruva-mcp
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `memory_upsert` | Insert/update vectors in a namespace (Pinecone-compatible) |
+| `memory_query`  | Top-K cosine search |
+| `memory_delete` | Delete by id |
+| `hd_kg_add_fact` | Add (subject, relation, object) to a KG |
+| `hd_kg_query` | Query KG for object of (subject, relation) |
+| `hd_analogy` | Four-term analogy in HD feature space |
+| `hd_causal_query` | Observational / interventional query on stored SCM |
+| `hd_plan` | EFE active-inference planner |
+
+## Env
+
+| Variable | Default |
+|---|---|
+| `NERUVA_API_KEY` | required |
+| `NERUVA_URL` | `https://api.neruva.io` |
+
+## License
+
+MIT — Clouthier Simulation Labs.

neruva_mcp-0.1.0/src/neruva_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/neruva_mcp/__init__.py
+src/neruva_mcp/py.typed
+src/neruva_mcp/server.py
+src/neruva_mcp.egg-info/PKG-INFO
+src/neruva_mcp.egg-info/SOURCES.txt
+src/neruva_mcp.egg-info/dependency_links.txt
+src/neruva_mcp.egg-info/entry_points.txt
+src/neruva_mcp.egg-info/requires.txt
+src/neruva_mcp.egg-info/top_level.txt

neruva_mcp-0.1.0/src/neruva_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

neruva_mcp-0.1.0/src/neruva_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+neruva-mcp = neruva_mcp.server:main

neruva_mcp-0.1.0/src/neruva_mcp.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mcp>=1.0.0
+httpx>=0.27

neruva_mcp-0.1.0/src/neruva_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+neruva_mcp