hebbianvault-mcp 0.2.0__tar.gz

hebbianvault_mcp-0.2.0/.gitignore

@@ -0,0 +1,27 @@
+# Node
+node_modules/
+dist/
+*.js.map
+*.d.ts.map
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+*.dist-info/
+.venv/
+.uv/
+
+# Test / coverage artifacts
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/

hebbianvault_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: hebbianvault-mcp
+Version: 0.2.0
+Summary: Customer-installable MCP server for the Hebbian tenant brain (Python). Same 8 tools as the Node.js sibling @hebbianvault/mcp.
+Author-email: Hebbian <hello@hebbian.ai>
+License: Apache-2.0
+Keywords: ai-tools,hebbian,knowledge-graph,mcp,model-context-protocol
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# hebbianvault-mcp (Python)
+
+Python sibling of `@hebbianvault/mcp`. Connect a Python MCP host to your Hebbian workspace — same 8 tools, same configuration. A thin client; all intelligence and access control live in the Hebbian service.
+
+## Quick start
+
+```bash
+pip install hebbianvault-mcp
+# or with uv (preferred)
+uv add hebbianvault-mcp
+```
+
+Generate a token from your Hebbian integrations page (AI Tools tab → Generate token).
+
+## Configuration
+
+Set `HEBBIAN_API_TOKEN` (or `HEBBIAN_TOKEN`) env var:
+
+```bash
+HEBBIAN_API_TOKEN=your_token_here hebbian-mcp
+```
+
+Or write `~/.config/hebbian/mcp-tenant.json`:
+
+```json
+{
+  "token": "your_token_here"
+}
+```
+
+| Variable | Purpose |
+|---|---|
+| `HEBBIAN_API_TOKEN` | Your token (required). `HEBBIAN_TOKEN` is also accepted. |
+| `HEBBIAN_API_URL` | Override the API base URL (Enterprise self-host). Defaults to the Hebbian SaaS API. |
+| `HEBBIAN_TENANT` | Optional workspace slug — only needed if your account belongs to more than one workspace. |
+
+## Generic agent config
+
+```python
+import os
+os.environ["HEBBIAN_API_TOKEN"] = "your_token_here"
+from hebbianvault_mcp import create_server
+server = create_server()
+# server.run() to start serving over stdio
+```
+
+## Token scope
+
+Your token decides what the adapter can see and do — a personal-workspace token gives access to your own knowledge; a company-workspace token gives access to the shared company workspace (where your role allows). Scope is decided by the Hebbian service.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `hebbian_read_node` | Read a single node by UUID |
+| `hebbian_search` | Find nodes in your workspace matching a query |
+| `hebbian_ask` | Ask a question and get an answer backed by source quotes |
+| `hebbian_capture` | Write a note into your workspace |
+| `hebbian_traverse` | Explore nodes connected to a starting node |
+| `hebbian_provenance` | See where a node's knowledge came from |
+| `hebbian_salience` | See a node's recent activity over time |
+| `hebbian_recent_activity` | Catch up on recent changes in your workspace |
+
+Results only ever include what your token is allowed to see.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+pytest
+ruff check src/ tests/
+```
+
+## Node.js version
+
+The canonical package is `@hebbianvault/mcp` on npm. This Python sibling has identical tools and configuration. Use whichever matches your MCP host environment.
+
+## License
+
+Apache-2.0. See the root [LICENSE](../LICENSE) file.

hebbianvault_mcp-0.2.0/README.md

@@ -0,0 +1,80 @@
+# hebbianvault-mcp (Python)
+
+Python sibling of `@hebbianvault/mcp`. Connect a Python MCP host to your Hebbian workspace — same 8 tools, same configuration. A thin client; all intelligence and access control live in the Hebbian service.
+
+## Quick start
+
+```bash
+pip install hebbianvault-mcp
+# or with uv (preferred)
+uv add hebbianvault-mcp
+```
+
+Generate a token from your Hebbian integrations page (AI Tools tab → Generate token).
+
+## Configuration
+
+Set `HEBBIAN_API_TOKEN` (or `HEBBIAN_TOKEN`) env var:
+
+```bash
+HEBBIAN_API_TOKEN=your_token_here hebbian-mcp
+```
+
+Or write `~/.config/hebbian/mcp-tenant.json`:
+
+```json
+{
+  "token": "your_token_here"
+}
+```
+
+| Variable | Purpose |
+|---|---|
+| `HEBBIAN_API_TOKEN` | Your token (required). `HEBBIAN_TOKEN` is also accepted. |
+| `HEBBIAN_API_URL` | Override the API base URL (Enterprise self-host). Defaults to the Hebbian SaaS API. |
+| `HEBBIAN_TENANT` | Optional workspace slug — only needed if your account belongs to more than one workspace. |
+
+## Generic agent config
+
+```python
+import os
+os.environ["HEBBIAN_API_TOKEN"] = "your_token_here"
+from hebbianvault_mcp import create_server
+server = create_server()
+# server.run() to start serving over stdio
+```
+
+## Token scope
+
+Your token decides what the adapter can see and do — a personal-workspace token gives access to your own knowledge; a company-workspace token gives access to the shared company workspace (where your role allows). Scope is decided by the Hebbian service.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `hebbian_read_node` | Read a single node by UUID |
+| `hebbian_search` | Find nodes in your workspace matching a query |
+| `hebbian_ask` | Ask a question and get an answer backed by source quotes |
+| `hebbian_capture` | Write a note into your workspace |
+| `hebbian_traverse` | Explore nodes connected to a starting node |
+| `hebbian_provenance` | See where a node's knowledge came from |
+| `hebbian_salience` | See a node's recent activity over time |
+| `hebbian_recent_activity` | Catch up on recent changes in your workspace |
+
+Results only ever include what your token is allowed to see.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+pytest
+ruff check src/ tests/
+```
+
+## Node.js version
+
+The canonical package is `@hebbianvault/mcp` on npm. This Python sibling has identical tools and configuration. Use whichever matches your MCP host environment.
+
+## License
+
+Apache-2.0. See the root [LICENSE](../LICENSE) file.

hebbianvault_mcp-0.2.0/conftest.py

@@ -0,0 +1,12 @@
+"""
+conftest.py — ensure src/ is on sys.path for pytest.
+
+Belt-and-braces for uv editable installs where the .pth file may not be
+processed (Python 3.11+ + uv venv combinations). See coding-factory LEARNINGS
+2026-05-15.
+"""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "src"))

hebbianvault_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hebbianvault-mcp"
+version = "0.2.0"
+description = "Customer-installable MCP server for the Hebbian tenant brain (Python). Same 8 tools as the Node.js sibling @hebbianvault/mcp."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.11"
+keywords = ["mcp", "hebbian", "knowledge-graph", "ai-tools", "model-context-protocol"]
+authors = [
+    { name = "Hebbian", email = "hello@hebbian.ai" }
+]
+
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.5",
+    "pyright>=1.1",
+]
+
+[project.scripts]
+hebbian-mcp = "hebbianvault_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hebbianvault_mcp"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "ANN", "S", "B", "UP"]
+ignore = ["ANN101", "ANN102", "S101"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["E501", "S105", "ANN401"]
+"src/hebbianvault_mcp/client.py" = ["ANN401"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "basic"
+include = ["src", "tests"]

hebbianvault_mcp-0.2.0/src/hebbianvault_mcp/__init__.py

@@ -0,0 +1,19 @@
+"""
+hebbianvault_mcp — Customer-installable MCP server for the Hebbian tenant brain.
+
+One package, scope-by-token (Employee or Company). Install in any MCP-compatible
+Python environment. Configure with a token issued from your Hebbian integrations page.
+
+Usage:
+    $ hebbian-mcp
+
+Or programmatically:
+    from hebbianvault_mcp import create_server
+    server = create_server()
+    server.run()
+"""
+
+from .server import create_server, main
+
+__all__ = ["create_server", "main"]
+__version__ = "0.1.0"

hebbianvault_mcp-0.2.0/src/hebbianvault_mcp/client.py

@@ -0,0 +1,118 @@
+"""
+hebbianvault_mcp.client — HTTPS client for the Hebbian API.
+
+- Adds Authorization: Bearer header to every request.
+- Surfaces API errors as HebbianApiError with status_code + error_code + message.
+- No business logic — thin transport wrapper over httpx.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+USER_AGENT = "hebbianvault-mcp/0.2.0 (Python)"
+
+
+class HebbianApiError(Exception):
+    """Structured API error returned by the Hebbian API."""
+
+    def __init__(
+        self,
+        status_code: int,
+        error_code: str,
+        message: str,
+        detail: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.detail = detail
+
+    def to_tool_error(self) -> str:
+        """Human-readable string for MCP tool error responses."""
+        if self.status_code == 401:
+            return (
+                f"Authentication failed ({self.error_code}): {self}. "
+                "Your token may be expired or revoked. "
+                "Generate a new token from the AI Tools tab in your Hebbian integrations page."
+            )
+        if self.status_code == 403:
+            return (
+                f"Permission denied ({self.error_code}): {self}. "
+                "Check that your token scope (employee/company) matches the operation."
+            )
+        if self.status_code == 404:
+            return f"Not found ({self.error_code}): {self}"
+        if self.status_code == 429:
+            return f"Rate limit exceeded ({self.error_code}): {self}. Slow down and retry."
+        return f"API error {self.status_code} ({self.error_code}): {self}"
+
+
+class HebbianClient:
+    """Thin async HTTP client for the Hebbian API."""
+
+    def __init__(self, api_url: str, token: str, tenant: str | None = None) -> None:
+        # Normalise: strip trailing slash
+        self._api_url = api_url.rstrip("/")
+        self._headers = {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        # Only sent when the account belongs to more than one workspace; the API
+        # resolves the single-membership case from the token alone.
+        if tenant and tenant.strip():
+            self._headers["X-Hebbian-Tenant"] = tenant.strip()
+
+    async def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """Execute a GET request and return parsed JSON."""
+        url = f"{self._api_url}{path}"
+        async with httpx.AsyncClient() as http:
+            response = await http.get(url, headers=self._headers, params=params)
+        return await self._handle_response(response)
+
+    async def post(self, path: str, body: dict[str, Any]) -> Any:
+        """Execute a POST request and return parsed JSON."""
+        url = f"{self._api_url}{path}"
+        async with httpx.AsyncClient() as http:
+            response = await http.post(
+                url,
+                headers={**self._headers, "Content-Type": "application/json"},
+                content=json.dumps(body).encode(),
+            )
+        return await self._handle_response(response)
+
+    @staticmethod
+    async def _handle_response(response: httpx.Response) -> Any:
+        """Parse and validate a response. Raises HebbianApiError on non-2xx."""
+        if response.is_success:
+            return response.json()
+
+        # Try to parse structured error body
+        error_code = f"HTTP_{response.status_code}"
+        message = response.reason_phrase or f"Status {response.status_code}"
+        detail = None
+        try:
+            body = response.json()
+            error_code = body.get("code") or body.get("error") or error_code
+            message = body.get("message") or body.get("error") or message
+            detail = body.get("detail")
+        except Exception:  # noqa: BLE001
+            message = response.text or message
+
+        raise HebbianApiError(
+            status_code=response.status_code,
+            error_code=error_code,
+            message=message,
+            detail=detail,
+        )

hebbianvault_mcp-0.2.0/src/hebbianvault_mcp/config.py

@@ -0,0 +1,106 @@
+"""
+hebbianvault_mcp.config — Configuration loading.
+
+Auth: bearer token from HEBBIAN_API_TOKEN env var (preferred) or
+      HEBBIAN_TOKEN (alternative) or config-file JSON path.
+URL:  HEBBIAN_API_URL env var (default: the Hebbian SaaS API).
+Tenant: HEBBIAN_TENANT (optional) — only needed when your account belongs to
+      more than one Hebbian workspace.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Hebbian SaaS API. Enterprise/self-host customers override with HEBBIAN_API_URL.
+DEFAULT_API_URL = "https://api.hebbianvault.com"
+
+
+@dataclass(frozen=True)
+class HebbianConfig:
+    """Resolved configuration for the MCP server."""
+
+    api_url: str
+    """Base URL of the Hebbian API. Configurable for Enterprise self-host."""
+
+    token: str
+    """Bearer token for authentication. Never log this value."""
+
+    tenant: str | None = None
+    """Optional workspace slug; sent as X-Hebbian-Tenant when set."""
+
+
+def load_config() -> HebbianConfig:
+    """
+    Load configuration from environment variables and optional config file.
+
+    Priority (highest first):
+      1. HEBBIAN_API_TOKEN / HEBBIAN_TOKEN env vars
+      2. HEBBIAN_CONFIG_PATH — path to a JSON config file
+      3. ~/.config/hebbian/mcp-tenant.json
+
+    Raises:
+        RuntimeError: if no token can be resolved.
+    """
+    api_url = os.environ.get("HEBBIAN_API_URL", DEFAULT_API_URL)
+    env_tenant = (os.environ.get("HEBBIAN_TENANT") or "").strip() or None
+
+    # ── Token from env ─────────────────────────────────────────────────────────
+    env_token = os.environ.get("HEBBIAN_API_TOKEN") or os.environ.get("HEBBIAN_TOKEN")
+    if env_token:
+        return HebbianConfig(api_url=api_url, token=env_token, tenant=env_tenant)
+
+    # ── Token from config file ─────────────────────────────────────────────────
+    config_path = _resolve_config_path()
+    if config_path:
+        file_cfg = _read_config_file(config_path)
+        if file_cfg.get("token"):
+            return HebbianConfig(
+                api_url=file_cfg.get("api_url", api_url),
+                token=file_cfg["token"],
+                tenant=env_tenant or file_cfg.get("tenant"),
+            )
+
+    raise RuntimeError(
+        "Hebbian MCP: No API token found. "
+        "Set HEBBIAN_API_TOKEN env var or HEBBIAN_TOKEN env var, "
+        "or write your token to ~/.config/hebbian/mcp-tenant.json as "
+        '{"token": "..."}. '
+        "Generate a token from the AI Tools tab in your Hebbian integrations page."
+    )
+
+
+def _resolve_config_path() -> Path | None:
+    """Resolve config file path — explicit env var or XDG default."""
+    explicit = os.environ.get("HEBBIAN_CONFIG_PATH")
+    if explicit:
+        p = Path(explicit).expanduser().resolve()
+        if p.exists():
+            return p
+        logger.warning(
+            "HEBBIAN_CONFIG_PATH set to %r but file not found.", explicit
+        )
+        return None
+
+    home = Path.home()
+    default = home / ".config" / "hebbian" / "mcp-tenant.json"
+    return default if default.exists() else None
+
+
+def _read_config_file(path: Path) -> dict[str, str]:
+    """Read and parse a JSON config file; tolerates missing fields."""
+    try:
+        raw = path.read_text(encoding="utf-8")
+        parsed = json.loads(raw)
+        if not isinstance(parsed, dict):
+            raise ValueError("Config file must be a JSON object")
+        return {k: str(v) for k, v in parsed.items() if isinstance(v, str)}
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Could not read config file at %r: %s", str(path), exc)
+        return {}

hebbianvault_mcp-0.2.0/src/hebbianvault_mcp/server.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""
+hebbianvault_mcp.server — MCP server entry point.
+
+Boots the Hebbian tenant MCP server over stdio transport.
+
+Usage:
+    python -m hebbianvault_mcp.server
+    hebbian-mcp          # via pyproject.toml [project.scripts]
+
+Auth:
+    HEBBIAN_API_TOKEN env var (or HEBBIAN_TOKEN)
+    or ~/.config/hebbian/mcp-tenant.json with {"token": "hbn_..."}
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from .client import HebbianClient
+from .config import load_config
+from .tools import TOOL_HANDLERS, TOOL_SCHEMAS
+
+logging.basicConfig(
+    level=logging.WARNING,
+    stream=sys.stderr,
+    format="%(asctime)s [%(name)s] %(levelname)s %(message)s",
+)
+logger = logging.getLogger("hebbianvault_mcp")
+
+SERVER_NAME = "hebbianvault-mcp"
+SERVER_VERSION = "0.1.0"
+
+
+def create_server() -> Server:
+    """
+    Create and configure the Hebbian MCP server.
+
+    Call server.run() or use as an async context to start serving.
+    """
+    config = load_config()
+    client = HebbianClient(api_url=config.api_url, token=config.token, tenant=config.tenant)
+
+    app = Server(SERVER_NAME)
+
+    @app.list_tools()
+    async def list_tools() -> list[Tool]:  # type: ignore[override]
+        return [
+            Tool(
+                name=schema["name"],
+                description=schema["description"],
+                inputSchema=schema["inputSchema"],
+            )
+            for schema in TOOL_SCHEMAS
+        ]
+
+    @app.call_tool()
+    async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:  # type: ignore[override]
+        handler = TOOL_HANDLERS.get(name)
+        if handler is None:
+            return [
+                TextContent(
+                    type="text",
+                    text=f"Unknown tool: {name}. Available tools: {', '.join(TOOL_HANDLERS)}",
+                )
+            ]
+        try:
+            result = await handler(client, arguments or {})
+            return [TextContent(type="text", text=result)]
+        except Exception as exc:  # noqa: BLE001
+            logger.error("Tool %r raised: %s", name, exc)
+            return [TextContent(type="text", text=f"Error: {exc}")]
+
+    logger.info(
+        "%s@%s started. API: %s",
+        SERVER_NAME,
+        SERVER_VERSION,
+        config.api_url,
+    )
+    return app
+
+
+def main() -> None:
+    """Entry point for `hebbian-mcp` CLI command."""
+    server = create_server()
+
+    async def _run() -> None:
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                server.create_initialization_options(),
+            )
+
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()