aevum-mcp 0.2.0__tar.gz

aevum_mcp-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+*.egg-info/
+
+# Build
+dist/
+build/
+
+# Tools
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Verify scripts (run locally, never commit)
+verify_phase*.py
+scripts/verify_phase*.py

aevum_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: aevum-mcp
+Version: 0.2.0
+Summary: Aevum — MCP server exposing the five functions as tools.
+Project-URL: Homepage, https://aevum.build
+Project-URL: Repository, https://github.com/aevum-labs/aevum
+License: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aevum-core
+Requires-Dist: mcp>=1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aevum-mcp
+
+MCP server for Aevum — exposes all five governed functions (`ingest`, `query`, `review`, `commit`, `replay`) as MCP tools, plus A2A task management.
+
+```bash
+pip install aevum-mcp
+python -m aevum.mcp
+```
+
+Compatible with Claude Desktop and any MCP client. See the [main repository README](https://github.com/aevum-labs/aevum) for configuration.

aevum_mcp-0.2.0/README.md

@@ -0,0 +1,10 @@
+# aevum-mcp
+
+MCP server for Aevum — exposes all five governed functions (`ingest`, `query`, `review`, `commit`, `replay`) as MCP tools, plus A2A task management.
+
+```bash
+pip install aevum-mcp
+python -m aevum.mcp
+```
+
+Compatible with Claude Desktop and any MCP client. See the [main repository README](https://github.com/aevum-labs/aevum) for configuration.

aevum_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "aevum-mcp"
+version = "0.2.0"
+description = "Aevum — MCP server exposing the five functions as tools."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aevum-core",
+    "mcp>=1.0",
+]
+
+[project.scripts]
+aevum-mcp = "aevum.mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://aevum.build"
+Repository = "https://github.com/aevum-labs/aevum"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aevum"]
+
+[tool.uv.sources]
+aevum-core = { workspace = true }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "--tb=short"
+pythonpath = ["src", "tests"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+mypy_path = "src"
+explicit_package_bases = true
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 130
+
+[tool.ruff.lint]
+select = ["E", "F", "UP", "B", "SIM", "I", "ANN"]
+ignore = ["ANN401"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.10",
+    "ruff>=0.9",
+]

aevum_mcp-0.2.0/src/aevum/mcp/__init__.py

@@ -0,0 +1,22 @@
+"""
+aevum.mcp — MCP server exposing Aevum's five functions as tools.
+
+Claude Desktop config (~/.claude/claude_desktop_config.json):
+    {
+      "mcpServers": {
+        "aevum": {
+          "command": "python",
+          "args": ["-m", "aevum.mcp"],
+          "env": {
+            "AEVUM_API_KEY": "your-key-here"
+          }
+        }
+      }
+    }
+"""
+
+from aevum.mcp.server import create_server
+
+__version__ = "0.1.0"
+
+__all__ = ["create_server"]

aevum_mcp-0.2.0/src/aevum/mcp/__main__.py

@@ -0,0 +1,29 @@
+"""
+python -m aevum.mcp — start the Aevum MCP server (stdio transport).
+
+For Claude Desktop, register in ~/.claude/claude_desktop_config.json:
+    {
+      "mcpServers": {
+        "aevum": {
+          "command": "python",
+          "args": ["-m", "aevum.mcp"]
+        }
+      }
+    }
+"""
+
+from __future__ import annotations
+
+from aevum.core.engine import Engine
+
+from aevum.mcp.server import create_server
+
+
+def main() -> None:
+    engine = Engine()
+    mcp = create_server(engine)
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

aevum_mcp-0.2.0/src/aevum/mcp/a2a.py

@@ -0,0 +1,95 @@
+"""
+A2A task format — Pydantic model and state machine for agent-to-agent task exchange.
+
+Task states: created, working, input_required, completed, failed, cancelled.
+Task IDs map directly to Aevum audit_ids for provenance tracking.
+A full A2A HTTP server is not included; the MCP tools provide the integration surface.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+A2ATaskState = Literal[
+    "created", "working", "input_required", "completed", "failed", "cancelled"
+]
+
+
+class A2AMessage(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    role: Literal["user", "agent"]
+    content: str
+    timestamp: str | None = None
+
+
+class A2AArtifact(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    artifact_id: str
+    name: str
+    content: str
+    mime_type: str = "text/plain"
+
+
+class A2ATask(BaseModel):
+    """
+    A2A-compatible task representation.
+
+    The aevum audit_id maps to the A2A task_id.
+    Task state maps to ledger event types:
+        created       -> commit(event_type="agent.task.created")
+        working       -> commit(event_type="agent.task.working")
+        input_required -> pending_review (review_required=True)
+        completed     -> commit(event_type="agent.task.completed")
+        failed        -> commit(event_type="agent.task.failed")
+        cancelled     -> commit(event_type="agent.task.cancelled")
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    task_id: str                      # maps to aevum audit_id
+    name: str
+    state: A2ATaskState
+    description: str = ""
+    messages: list[A2AMessage] = []
+    artifacts: list[A2AArtifact] = []
+    metadata: dict[str, Any] = {}
+
+    @classmethod
+    def created(cls, task_id: str, name: str, description: str = "") -> A2ATask:
+        return cls(task_id=task_id, name=name, state="created", description=description)
+
+    @classmethod
+    def completed(
+        cls,
+        task_id: str,
+        name: str,
+        result: str,
+        artifacts: list[A2AArtifact] | None = None,
+    ) -> A2ATask:
+        return cls(
+            task_id=task_id,
+            name=name,
+            state="completed",
+            messages=[A2AMessage(role="agent", content=result)],
+            artifacts=artifacts or [],
+        )
+
+    @classmethod
+    def input_required(cls, task_id: str, name: str, prompt: str) -> A2ATask:
+        return cls(
+            task_id=task_id,
+            name=name,
+            state="input_required",
+            messages=[A2AMessage(role="agent", content=prompt)],
+        )
+
+    @classmethod
+    def failed(cls, task_id: str, name: str, error: str) -> A2ATask:
+        return cls(
+            task_id=task_id,
+            name=name,
+            state="failed",
+            messages=[A2AMessage(role="agent", content=f"Task failed: {error}")],
+        )

aevum_mcp-0.2.0/src/aevum/mcp/server.py

@@ -0,0 +1,209 @@
+"""
+Aevum MCP server — five governed functions exposed as MCP tools, plus two
+A2A task tools (create_task, get_task) backed by the episodic ledger.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aevum.core.engine import Engine
+
+from aevum.mcp.a2a import A2ATask
+from mcp.server.fastmcp import FastMCP
+
+
+def create_server(engine: Engine | None = None) -> FastMCP:
+    """
+    Create the Aevum MCP server.
+
+    Args:
+        engine: Aevum kernel. Uses Engine() with in-memory defaults if None.
+
+    Returns:
+        Configured FastMCP server instance.
+    """
+    _engine = engine or Engine()
+    mcp = FastMCP("aevum")
+
+    @mcp.tool()
+    def ingest(
+        data: dict[str, Any],
+        provenance: dict[str, Any],
+        purpose: str,
+        subject_id: str,
+        actor: str = "mcp-user",
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Move data through the governed membrane into the Aevum knowledge graph.
+
+        Requires an active consent grant for the actor + subject_id + purpose.
+        Returns an OutputEnvelope with status (ok/error/crisis) and audit_id.
+        """
+        result = _engine.ingest(
+            data=data,
+            provenance=provenance,
+            purpose=purpose,
+            subject_id=subject_id,
+            actor=actor,
+            idempotency_key=idempotency_key,
+        )
+        return result.model_dump(mode="json")
+
+    @mcp.tool()
+    def query(
+        purpose: str,
+        subject_ids: list[str],
+        actor: str = "mcp-user",
+        classification_max: int = 0,
+    ) -> dict[str, Any]:
+        """
+        Traverse the Aevum knowledge graph and return context for the declared purpose.
+
+        Requires consent grants for all subject_ids. Results are filtered by
+        classification_max (Barrier 2). Active complications contribute to results.
+        Returns an OutputEnvelope with the assembled context.
+        """
+        result = _engine.query(
+            purpose=purpose,
+            subject_ids=subject_ids,
+            actor=actor,
+            classification_max=classification_max,
+        )
+        return result.model_dump(mode="json")
+
+    @mcp.tool()
+    def review(
+        audit_id: str,
+        action: str | None = None,
+        actor: str = "mcp-user",
+    ) -> dict[str, Any]:
+        """
+        Get status of or act on a pending human review gate.
+
+        action: None = poll status, "approve" = approve, "veto" = veto.
+        Veto-as-default: if a deadline was set and has elapsed, silence = veto.
+        Returns an OutputEnvelope with review status.
+        """
+        result = _engine.review(
+            audit_id=audit_id,
+            actor=actor,
+            action=action,
+        )
+        return result.model_dump(mode="json")
+
+    @mcp.tool()
+    def commit(
+        event_type: str,
+        payload: dict[str, Any],
+        actor: str = "mcp-user",
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Append an event to the Aevum episodic ledger.
+
+        event_type must not use kernel-reserved prefixes (ingest., query., etc.).
+        Use a namespaced prefix: "myapp.user_action", "myapp.decision", etc.
+        Returns an OutputEnvelope with the new entry's audit_id.
+        """
+        result = _engine.commit(
+            event_type=event_type,
+            payload=payload,
+            actor=actor,
+            idempotency_key=idempotency_key,
+        )
+        return result.model_dump(mode="json")
+
+    @mcp.tool()
+    def replay(
+        audit_id: str,
+        actor: str = "mcp-user",
+    ) -> dict[str, Any]:
+        """
+        Reconstruct a past Aevum decision faithfully.
+
+        Returns the original ledger entry payload as it existed at the time
+        it was recorded. The reconstruction is deterministic and read-only.
+        Requires consent for the replay operation on the original subject.
+        """
+        result = _engine.replay(
+            audit_id=audit_id,
+            actor=actor,
+        )
+        return result.model_dump(mode="json")
+
+    @mcp.tool()
+    def create_task(
+        name: str,
+        description: str = "",
+        payload: dict[str, Any] | None = None,
+        actor: str = "mcp-user",
+    ) -> dict[str, Any]:
+        """
+        Create an A2A-compatible task and record it in the Aevum ledger.
+
+        The returned task_id is an aevum audit_id (urn:aevum:audit:...).
+        Poll task status with get_task(task_id).
+        Task state transitions are tracked via ledger events.
+        """
+        committed = _engine.commit(
+            event_type="agent.task.created",
+            payload={
+                "name": name,
+                "description": description,
+                "task_payload": payload or {},
+            },
+            actor=actor,
+        )
+        task = A2ATask.created(
+            task_id=committed.audit_id,
+            name=name,
+            description=description,
+        )
+        return task.model_dump(mode="json")
+
+    @mcp.tool()
+    def get_task(
+        task_id: str,
+        actor: str = "mcp-user",
+    ) -> dict[str, Any]:
+        """
+        Get the current state of an A2A task by its audit_id.
+
+        Replays the ledger entry to reconstruct task state.
+        Returns an A2ATask with the current state and any messages.
+        """
+        replayed = _engine.replay(audit_id=task_id, actor=actor)
+
+        if replayed.status == "error":
+            task = A2ATask.failed(
+                task_id=task_id,
+                name="unknown",
+                error=replayed.data.get("error_detail", "Task not found"),
+            )
+            return task.model_dump(mode="json")
+
+        original_payload = replayed.data.get("replayed_payload", {})
+        name = original_payload.get("name", "task")
+
+        # Map ledger event_type to A2A state
+        event_type = original_payload.get("event_type", "agent.task.created")
+        state_map = {
+            "agent.task.created": "created",
+            "agent.task.working": "working",
+            "agent.task.completed": "completed",
+            "agent.task.failed": "failed",
+            "agent.task.cancelled": "cancelled",
+        }
+        a2a_state = state_map.get(event_type, "created")
+
+        task = A2ATask(
+            task_id=task_id,
+            name=name,
+            state=a2a_state,  # type: ignore[arg-type]
+            description=original_payload.get("description", ""),
+        )
+        return task.model_dump(mode="json")
+
+    return mcp

aevum_mcp-0.2.0/tests/test_a2a.py

@@ -0,0 +1,88 @@
+"""
+Tests for A2A task format and MCP tools.
+Uses direct tool invocation -- no real MCP protocol.
+
+NO tests/__init__.py (standing rule).
+"""
+
+from __future__ import annotations
+
+import json
+
+from aevum.core.engine import Engine
+
+from aevum.mcp.a2a import A2ATask
+from aevum.mcp.server import create_server
+
+
+class TestA2AModels:
+    def test_created_task(self) -> None:
+        task = A2ATask.created("urn:aevum:audit:abc", "Test Task", "desc")
+        assert task.task_id == "urn:aevum:audit:abc"
+        assert task.state == "created"
+        assert task.name == "Test Task"
+
+    def test_completed_task(self) -> None:
+        task = A2ATask.completed("urn:aevum:audit:abc", "Test", "Done successfully")
+        assert task.state == "completed"
+        assert len(task.messages) == 1
+        assert task.messages[0].role == "agent"
+
+    def test_failed_task(self) -> None:
+        task = A2ATask.failed("urn:aevum:audit:abc", "Test", "Something went wrong")
+        assert task.state == "failed"
+
+    def test_input_required_task(self) -> None:
+        task = A2ATask.input_required("urn:aevum:audit:abc", "Test", "Need approval")
+        assert task.state == "input_required"
+
+    def test_task_serializable(self) -> None:
+        task = A2ATask.created("urn:aevum:audit:abc", "Test")
+        # Must be JSON-serializable (MCP protocol requirement)
+        json.dumps(task.model_dump(mode="json"))
+
+    def test_valid_states(self) -> None:
+        valid = ["created", "working", "input_required", "completed", "failed", "cancelled"]
+        for state in valid:
+            task = A2ATask(task_id="urn:aevum:audit:abc", name="t", state=state)  # type: ignore[arg-type]
+            assert task.state == state
+
+
+class TestA2AMcpTools:
+    def test_create_task_tool(self) -> None:
+        mcp = create_server(Engine())
+        tool_fn = mcp._tool_manager._tools["create_task"].fn  # type: ignore[attr-defined]
+        result = tool_fn(name="Test Task", description="A test", payload={"x": 1})
+        assert result["state"] == "created"
+        assert result["task_id"].startswith("urn:aevum:audit:")
+        assert result["name"] == "Test Task"
+
+    def test_get_task_tool(self) -> None:
+        mcp = create_server(Engine())
+        create_fn = mcp._tool_manager._tools["create_task"].fn  # type: ignore[attr-defined]
+        get_fn = mcp._tool_manager._tools["get_task"].fn  # type: ignore[attr-defined]
+
+        created = create_fn(name="Fetch Me", description="test")
+        task_id = created["task_id"]
+
+        fetched = get_fn(task_id=task_id)
+        assert fetched["task_id"] == task_id
+
+    def test_get_task_not_found(self) -> None:
+        mcp = create_server(Engine())
+        get_fn = mcp._tool_manager._tools["get_task"].fn  # type: ignore[attr-defined]
+        result = get_fn(task_id="urn:aevum:audit:00000000-0000-7000-8000-000000000999")
+        assert result["state"] == "failed"
+
+    def test_seven_tools_registered(self) -> None:
+        mcp = create_server(Engine())
+        tools = set(mcp._tool_manager._tools.keys())  # type: ignore[attr-defined]
+        for expected in ["ingest", "query", "review", "commit", "replay",
+                         "create_task", "get_task"]:
+            assert expected in tools, f"Missing tool: {expected}"
+
+    def test_create_task_result_json_serializable(self) -> None:
+        mcp = create_server(Engine())
+        tool_fn = mcp._tool_manager._tools["create_task"].fn  # type: ignore[attr-defined]
+        result = tool_fn(name="Test", payload={})
+        json.dumps(result)  # Must not raise

aevum_mcp-0.2.0/tests/test_server.py

@@ -0,0 +1,143 @@
+"""
+Tests for aevum-mcp server.
+
+Tests call tool functions directly — no stdio protocol in CI.
+The MCP server registration and tool schema are verified separately.
+
+NO tests/__init__.py (standing rule).
+"""
+
+from __future__ import annotations
+
+import json
+
+from aevum.core.consent.models import ConsentGrant
+from aevum.core.engine import Engine
+
+from aevum.mcp.server import create_server
+
+
+def _engine_with_consent() -> Engine:
+    engine = Engine()
+    engine.add_consent_grant(ConsentGrant(
+        grant_id="g1",
+        subject_id="subject-1",
+        grantee_id="mcp-user",
+        operations=["ingest", "query", "replay", "export"],
+        purpose="mcp-testing",
+        classification_max=3,
+        granted_at="2026-01-01T00:00:00Z",
+        expires_at="2030-01-01T00:00:00Z",
+    ))
+    return engine
+
+
+def _prov() -> dict:  # type: ignore[type-arg]
+    return {
+        "source_id": "test-src",
+        "chain_of_custody": ["test-src"],
+        "classification": 0,
+        "ingest_audit_id": "urn:aevum:audit:00000000-0000-7000-8000-000000000001",
+        "model_id": None,
+    }
+
+
+def test_server_creates_successfully() -> None:
+    mcp = create_server()
+    assert mcp is not None
+    assert mcp.name == "aevum"
+
+
+def test_five_tools_registered() -> None:
+    mcp = create_server()
+    tool_names = list(mcp._tool_manager._tools.keys())  # type: ignore[attr-defined]
+    for expected in ["ingest", "query", "review", "commit", "replay"]:
+        assert expected in tool_names, f"Tool '{expected}' not registered"
+
+
+def test_commit_tool_returns_envelope() -> None:
+    mcp = create_server(engine=Engine())
+    tool_fn = mcp._tool_manager._tools["commit"].fn  # type: ignore[attr-defined]
+    result = tool_fn(
+        event_type="app.test",
+        payload={"k": "v"},
+        actor="mcp-user",
+    )
+    assert result["status"] == "ok"
+    assert result["audit_id"].startswith("urn:aevum:audit:")
+
+
+def test_ingest_tool_requires_consent() -> None:
+    mcp = create_server(engine=Engine())  # No consent grants
+    tool_fn = mcp._tool_manager._tools["ingest"].fn  # type: ignore[attr-defined]
+    result = tool_fn(
+        data={"content": "test"},
+        provenance=_prov(),
+        purpose="mcp-testing",
+        subject_id="subject-1",
+        actor="mcp-user",
+    )
+    assert result["status"] == "error"
+    assert result["data"]["error_code"] == "consent_required"
+
+
+def test_ingest_tool_with_consent() -> None:
+    mcp = create_server(engine=_engine_with_consent())
+    tool_fn = mcp._tool_manager._tools["ingest"].fn  # type: ignore[attr-defined]
+    result = tool_fn(
+        data={"content": "hello"},
+        provenance=_prov(),
+        purpose="mcp-testing",
+        subject_id="subject-1",
+        actor="mcp-user",
+    )
+    assert result["status"] == "ok"
+
+
+def test_query_tool_with_consent() -> None:
+    engine = _engine_with_consent()
+    mcp = create_server(engine=engine)
+
+    ingest_fn = mcp._tool_manager._tools["ingest"].fn  # type: ignore[attr-defined]
+    ingest_fn(data={"x": 1}, provenance=_prov(),
+              purpose="mcp-testing", subject_id="subject-1")
+
+    query_fn = mcp._tool_manager._tools["query"].fn  # type: ignore[attr-defined]
+    result = query_fn(purpose="mcp-testing", subject_ids=["subject-1"])
+    assert result["status"] == "ok"
+
+
+def test_replay_tool() -> None:
+    engine = Engine()
+    mcp = create_server(engine=engine)
+
+    commit_fn = mcp._tool_manager._tools["commit"].fn  # type: ignore[attr-defined]
+    committed = commit_fn(event_type="app.replayable", payload={"v": 42})
+    audit_id = committed["audit_id"]
+
+    replay_fn = mcp._tool_manager._tools["replay"].fn  # type: ignore[attr-defined]
+    result = replay_fn(audit_id=audit_id)
+    assert result["status"] == "ok"
+    assert result["data"]["replayed_payload"]["v"] == 42
+
+
+def test_crisis_content_returns_crisis() -> None:
+    mcp = create_server(engine=Engine())
+    tool_fn = mcp._tool_manager._tools["ingest"].fn  # type: ignore[attr-defined]
+    result = tool_fn(
+        data={"content": "I want to kill myself"},
+        provenance=_prov(),
+        purpose="test",
+        subject_id="subject-1",
+    )
+    assert result["status"] == "crisis"
+
+
+def test_all_tools_return_serializable_dicts() -> None:
+    """MCP protocol requires JSON-serializable return values."""
+    engine = Engine()
+    mcp = create_server(engine=engine)
+
+    commit_fn = mcp._tool_manager._tools["commit"].fn  # type: ignore[attr-defined]
+    result = commit_fn(event_type="app.ser_test", payload={"k": "v"})
+    json.dumps(result)