cortexdb-mcp 0.2.0__py3-none-any.whl

cortexdb_mcp/server.py

@@ -0,0 +1,1085 @@
+"""CortexDB MCP Server.
+
+Exposes the full CortexDB API (memory, episodes, entities, knowledge graph,
+search, usage, export/import) as MCP tools, resources, and prompts so that any
+MCP-compatible AI tool can interact with CortexDB's long-term memory system.
+
+Supported clients: Claude Desktop, Cursor, Windsurf, VS Code Copilot, and any
+tool that speaks the Model Context Protocol.
+
+Usage::
+
+    cortexdb-mcp                  # stdio transport (default)
+    python -m cortexdb_mcp.server
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+from cortexdb_mcp.config import CortexMCPConfig
+from cortexdb_mcp.insights import InsightsEngine
+
+logger = logging.getLogger("cortexdb_mcp")
+
+# ---------------------------------------------------------------------------
+# Server & config
+# ---------------------------------------------------------------------------
+
+mcp = FastMCP(
+    "cortexdb",
+    instructions=(
+        "CortexDB is a long-term memory layer for AI systems. "
+        "Use these tools to store, search, and manage memories. "
+        "Memories are stored as immutable events and indexed into a knowledge graph. "
+        "Use memory_store to save information, memory_search or get_context to retrieve it, "
+        "and entity tools to explore the knowledge graph."
+    ),
+)
+_config = CortexMCPConfig.from_env()
+
+
+def _client() -> httpx.AsyncClient:
+    """Return a configured ``httpx.AsyncClient`` for CortexDB."""
+    headers: dict[str, str] = {"Content-Type": "application/json"}
+    if _config.api_key:
+        headers["Authorization"] = f"Bearer {_config.api_key}"
+    return httpx.AsyncClient(
+        base_url=_config.url,
+        headers=headers,
+        timeout=_config.timeout,
+    )
+
+
+async def _request(
+    method: str,
+    path: str,
+    *,
+    json_body: dict[str, Any] | None = None,
+    params: dict[str, Any] | None = None,
+    extra_headers: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """Execute an HTTP request against CortexDB and return parsed JSON."""
+    async with _client() as client:
+        try:
+            kwargs: dict[str, Any] = {}
+            if json_body is not None:
+                kwargs["json"] = json_body
+            if params is not None:
+                kwargs["params"] = params
+            if extra_headers is not None:
+                kwargs["headers"] = extra_headers
+            response = await client.request(method, path, **kwargs)
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPStatusError as exc:
+            body = exc.response.text
+            raise RuntimeError(
+                f"CortexDB returned HTTP {exc.response.status_code}: {body}"
+            ) from exc
+        except httpx.RequestError as exc:
+            raise RuntimeError(
+                f"Failed to reach CortexDB at {_config.url}: {exc}"
+            ) from exc
+
+
+# ===========================================================================
+# TOOLS — Memory Operations
+# ===========================================================================
+
+
+@mcp.tool()
+async def memory_store(
+    content: str,
+    source: str | None = None,
+    episode_type: str = "message",
+    tenant_id: str | None = None,
+    namespace: str | None = None,
+    tags: list[str] | None = None,
+    ttl_seconds: int | None = None,
+) -> str:
+    """Store a new memory or episode in CortexDB.
+
+    Parameters
+    ----------
+    content:
+        The textual content to remember (max 1 MB).
+    source:
+        Origin of the memory (e.g. "slack", "github", "cursor").
+    episode_type:
+        Type of episode: message, code_change, incident, deployment, issue,
+        document, review, meeting, alert, decision, custom. Default "message".
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    namespace:
+        Logical namespace within the tenant.
+    tags:
+        Optional list of tags for categorisation.
+    ttl_seconds:
+        Auto-expiry time in seconds. Omit for permanent storage.
+    """
+    body: dict[str, Any] = {
+        "content": content,
+        "episode_type": episode_type,
+    }
+    if source is not None:
+        body["source"] = source
+    if tenant_id is not None:
+        body["tenant_id"] = tenant_id
+    if namespace is not None:
+        body["namespace"] = namespace
+    if tags is not None:
+        body["tags"] = tags
+    if ttl_seconds is not None:
+        body["ttl_seconds"] = ttl_seconds
+
+    path = "/v1/episodes" if source or tags else "/v1/remember"
+    result = await _request("POST", path, json_body=body)
+
+    event_id = result.get("event_id") or result.get("episode_id") or "unknown"
+    return f"Stored successfully. ID: {event_id}"
+
+
+@mcp.tool()
+async def memory_search(
+    query: str,
+    tenant_id: str | None = None,
+    max_results: int = 10,
+) -> str:
+    """Search CortexDB for relevant memories using hybrid retrieval (BM25 + vector + graph).
+
+    Parameters
+    ----------
+    query:
+        Natural-language search query.
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    max_results:
+        Maximum number of results to return (default 10).
+    """
+    body: dict[str, Any] = {
+        "query": query,
+        "max_results": max_results,
+    }
+    if tenant_id is not None:
+        body["tenant_id"] = tenant_id
+
+    result = await _request("POST", "/v1/recall", json_body=body)
+
+    context = result.get("context", "")
+    confidence = result.get("confidence")
+    items = result.get("results", [])
+
+    parts: list[str] = []
+    if context:
+        parts.append(context)
+    if items:
+        parts.append(f"\n--- {len(items)} result(s) ---")
+        for item in items:
+            parts.append(json.dumps(item, indent=2))
+    if confidence is not None:
+        parts.append(f"\nConfidence: {confidence}")
+
+    return "\n".join(parts) if parts else "No results found."
+
+
+@mcp.tool()
+async def memory_forget(
+    reason: str,
+    query: str | None = None,
+    tenant_id: str | None = None,
+) -> str:
+    """Delete memories from CortexDB (supports GDPR erasure).
+
+    Parameters
+    ----------
+    reason:
+        Reason for the deletion (required for audit trail).
+    query:
+        Optional query to select which memories to forget.
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    """
+    body: dict[str, Any] = {"reason": reason}
+    if query is not None:
+        body["query"] = query
+    if tenant_id is not None:
+        body["tenant_id"] = tenant_id
+
+    result = await _request("POST", "/v1/forget", json_body=body)
+
+    entities = result.get("entities_removed", result.get("forgotten_entities", 0))
+    edges = result.get("edges_removed", result.get("forgotten_edges", 0))
+    audit_id = result.get("audit_id", "")
+    msg = f"Forgotten. Entities removed: {entities}, edges removed: {edges}."
+    if audit_id:
+        msg += f" Audit ID: {audit_id}"
+    return msg
+
+
+@mcp.tool()
+async def get_context(
+    topic: str,
+    tenant_id: str | None = None,
+    include_graph: bool = False,
+) -> str:
+    """Retrieve rich contextual information about a topic from CortexDB.
+
+    Performs deep retrieval combining keyword search, vector similarity, and
+    knowledge graph traversal to build comprehensive context.
+
+    Parameters
+    ----------
+    topic:
+        The entity or topic to retrieve context for.
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    include_graph:
+        Whether to include graph relationships in the response.
+    """
+    body: dict[str, Any] = {
+        "query": topic,
+        "max_tokens": 4096,
+        "max_results": 50,
+    }
+    if tenant_id is not None:
+        body["tenant_id"] = tenant_id
+    if include_graph:
+        body["include_graph"] = True
+
+    result = await _request("POST", "/v1/recall", json_body=body)
+
+    context = result.get("context", "")
+    graph = result.get("graph")
+
+    parts: list[str] = []
+    if context:
+        parts.append(context)
+    if graph:
+        parts.append("\n--- Graph Relationships ---")
+        parts.append(json.dumps(graph, indent=2))
+
+    return "\n".join(parts) if parts else f"No context found for '{topic}'."
+
+
+@mcp.tool()
+async def advanced_search(
+    query: str,
+    tenant_id: str | None = None,
+    source: str | None = None,
+    episode_type: str | None = None,
+    time_range_start: str | None = None,
+    time_range_end: str | None = None,
+    limit: int = 20,
+    offset: int = 0,
+) -> str:
+    """Search CortexDB with structured filters.
+
+    Parameters
+    ----------
+    query:
+        Natural-language search query.
+    tenant_id:
+        Tenant scope.
+    source:
+        Filter by source (e.g. "slack", "github").
+    episode_type:
+        Filter by type (e.g. "incident", "code_change", "deployment").
+    time_range_start:
+        ISO 8601 start time (e.g. "2026-03-01T00:00:00Z").
+    time_range_end:
+        ISO 8601 end time.
+    limit:
+        Max results (default 20).
+    offset:
+        Pagination offset.
+    """
+    body: dict[str, Any] = {"query": query, "limit": limit, "offset": offset}
+    filters: dict[str, Any] = {}
+    if source:
+        filters["source"] = source
+    if episode_type:
+        filters["episode_type"] = episode_type
+    if time_range_start or time_range_end:
+        time_range: dict[str, str] = {}
+        if time_range_start:
+            time_range["start"] = time_range_start
+        if time_range_end:
+            time_range["end"] = time_range_end
+        filters["time_range"] = time_range
+    if filters:
+        body["filters"] = filters
+    if tenant_id:
+        body["tenant_id"] = tenant_id
+
+    result = await _request("POST", "/v1/search", json_body=body)
+
+    context = result.get("context", "")
+    episodes = result.get("episodes", [])
+    total = result.get("total_episodes", len(episodes))
+    confidence = result.get("confidence")
+
+    parts: list[str] = []
+    if context:
+        parts.append(context)
+    if episodes:
+        parts.append(f"\n--- {len(episodes)} of {total} episode(s) ---")
+        for ep in episodes:
+            ep_id = ep.get("episode_id", ep.get("id", ""))
+            ep_type = ep.get("episode_type", "")
+            created = ep.get("created_at", "")
+            snippet = (ep.get("content", "")[:150] + "...") if ep.get("content") else ""
+            parts.append(f"  [{ep_type}] {ep_id}  {created}")
+            if snippet:
+                parts.append(f"    {snippet}")
+    if confidence is not None:
+        parts.append(f"\nConfidence: {confidence}")
+
+    return "\n".join(parts) if parts else "No results found."
+
+
+# ===========================================================================
+# TOOLS — Episode CRUD
+# ===========================================================================
+
+
+@mcp.tool()
+async def memory_list(
+    tenant_id: str | None = None,
+    limit: int = 20,
+    offset: int = 0,
+    episode_type: str | None = None,
+) -> str:
+    """List memories / episodes stored in CortexDB with pagination.
+
+    Parameters
+    ----------
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    limit:
+        Maximum number of episodes to return (default 20).
+    offset:
+        Pagination offset (default 0).
+    episode_type:
+        Optional filter by episode type.
+    """
+    params: dict[str, Any] = {"limit": limit, "offset": offset}
+    if episode_type is not None:
+        params["episode_type"] = episode_type
+
+    extra_headers: dict[str, str] = {}
+    if tenant_id is not None:
+        extra_headers["x-tenant-id"] = tenant_id
+
+    result = await _request(
+        "GET", "/v1/episodes", params=params, extra_headers=extra_headers or None
+    )
+
+    episodes = result.get("episodes", result.get("items", []))
+    total = result.get("total", len(episodes))
+
+    if not episodes:
+        return "No episodes found."
+
+    parts: list[str] = [f"Showing {len(episodes)} of {total} episode(s):\n"]
+    for ep in episodes:
+        ep_id = ep.get("episode_id", ep.get("id", "unknown"))
+        ep_type = ep.get("episode_type", "unknown")
+        created = ep.get("created_at", "")
+        snippet = (ep.get("content", "")[:120] + "...") if ep.get("content") else ""
+        parts.append(f"  [{ep_type}] {ep_id}  {created}")
+        if snippet:
+            parts.append(f"    {snippet}")
+    return "\n".join(parts)
+
+
+@mcp.tool()
+async def memory_get(
+    episode_id: str,
+    tenant_id: str | None = None,
+) -> str:
+    """Get a specific memory / episode by its ID.
+
+    Parameters
+    ----------
+    episode_id:
+        The unique identifier of the episode to retrieve.
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    """
+    extra_headers: dict[str, str] = {}
+    if tenant_id is not None:
+        extra_headers["x-tenant-id"] = tenant_id
+
+    result = await _request(
+        "GET", f"/v1/episodes/{episode_id}", extra_headers=extra_headers or None
+    )
+
+    parts: list[str] = [
+        f"Episode: {result.get('episode_id', result.get('id', episode_id))}",
+        f"Type: {result.get('episode_type', 'unknown')}",
+    ]
+    if result.get("created_at"):
+        parts.append(f"Created: {result['created_at']}")
+    if result.get("source"):
+        parts.append(f"Source: {result['source']}")
+    if result.get("tags"):
+        parts.append(f"Tags: {', '.join(result['tags'])}")
+    if result.get("content"):
+        parts.append(f"\nContent:\n{result['content']}")
+    if result.get("metadata"):
+        parts.append(f"\nMetadata:\n{json.dumps(result['metadata'], indent=2)}")
+    return "\n".join(parts)
+
+
+@mcp.tool()
+async def memory_update(
+    episode_id: str,
+    content: str,
+    tenant_id: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> str:
+    """Update an existing memory's content or metadata.
+
+    Parameters
+    ----------
+    episode_id:
+        The unique identifier of the episode to update.
+    content:
+        New textual content for the episode.
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    metadata:
+        Optional metadata dictionary to merge into the episode.
+    """
+    body: dict[str, Any] = {"content": content}
+    if metadata is not None:
+        body["metadata"] = metadata
+
+    extra_headers: dict[str, str] = {}
+    if tenant_id is not None:
+        extra_headers["x-tenant-id"] = tenant_id
+
+    result = await _request(
+        "PUT", f"/v1/episodes/{episode_id}",
+        json_body=body, extra_headers=extra_headers or None,
+    )
+
+    updated_id = result.get("episode_id", result.get("id", episode_id))
+    return f"Updated successfully. Episode ID: {updated_id}"
+
+
+@mcp.tool()
+async def memory_delete(
+    episode_id: str,
+    tenant_id: str | None = None,
+) -> str:
+    """Delete a specific episode by ID.
+
+    Parameters
+    ----------
+    episode_id:
+        The unique identifier of the episode to delete.
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    """
+    extra_headers: dict[str, str] = {}
+    if tenant_id is not None:
+        extra_headers["x-tenant-id"] = tenant_id
+
+    await _request(
+        "DELETE", f"/v1/episodes/{episode_id}", extra_headers=extra_headers or None
+    )
+    return f"Deleted episode {episode_id}."
+
+
+@mcp.tool()
+async def memory_bulk_delete(
+    query: str,
+    reason: str,
+    tenant_id: str | None = None,
+    dry_run: bool = False,
+) -> str:
+    """Delete multiple memories matching a query pattern.
+
+    Parameters
+    ----------
+    query:
+        Search query to select memories for deletion.
+    reason:
+        Reason for the deletion (audit trail / GDPR).
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    dry_run:
+        If True, return the count of matching episodes without deleting.
+    """
+    body: dict[str, Any] = {"query": query, "reason": reason, "dry_run": dry_run}
+    if tenant_id is not None:
+        body["tenant_id"] = tenant_id
+
+    result = await _request("POST", "/v1/forget", json_body=body)
+
+    deleted = result.get("deleted", result.get("entities_removed", 0))
+    if dry_run:
+        return f"Dry run: {deleted} episode(s) would be deleted."
+    return f"Bulk delete complete. {deleted} episode(s) removed."
+
+
+# ===========================================================================
+# TOOLS — Knowledge Graph (Entities & Links)
+# ===========================================================================
+
+
+@mcp.tool()
+async def entity_list(
+    tenant_id: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> str:
+    """List entities in the CortexDB knowledge graph.
+
+    Entities are automatically extracted from memories — people, services,
+    projects, concepts, and more.
+
+    Parameters
+    ----------
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    limit:
+        Maximum number of entities to return (default 50).
+    offset:
+        Pagination offset.
+    """
+    params: dict[str, Any] = {"limit": limit, "offset": offset}
+    if tenant_id:
+        params["tenant_id"] = tenant_id
+
+    result = await _request("GET", "/v1/entities", params=params)
+
+    entities = result.get("entities", result.get("items", []))
+    if not entities:
+        return "No entities found."
+
+    parts: list[str] = [f"Found {len(entities)} entity/entities:\n"]
+    for ent in entities:
+        eid = ent.get("id", "")
+        name = ent.get("name", "unnamed")
+        etype = ent.get("entity_type", "unknown")
+        ep_count = ent.get("episode_count", 0)
+        parts.append(f"  [{etype}] {name} (id: {eid}, {ep_count} episodes)")
+    return "\n".join(parts)
+
+
+@mcp.tool()
+async def entity_get(
+    entity_id: str,
+    tenant_id: str | None = None,
+) -> str:
+    """Get detailed information about a specific entity including relationships.
+
+    Parameters
+    ----------
+    entity_id:
+        The unique identifier of the entity.
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    """
+    params: dict[str, Any] = {}
+    if tenant_id:
+        params["tenant_id"] = tenant_id
+
+    result = await _request("GET", f"/v1/entities/{entity_id}", params=params)
+
+    parts: list[str] = [
+        f"Entity: {result.get('name', 'unnamed')}",
+        f"Type: {result.get('entity_type', 'unknown')}",
+        f"ID: {result.get('id', entity_id)}",
+    ]
+    if result.get("first_seen"):
+        parts.append(f"First seen: {result['first_seen']}")
+    if result.get("last_seen"):
+        parts.append(f"Last seen: {result['last_seen']}")
+    if result.get("episode_count"):
+        parts.append(f"Episodes: {result['episode_count']}")
+
+    rels = result.get("relationships", [])
+    if rels:
+        parts.append(f"\n--- {len(rels)} Relationship(s) ---")
+        for rel in rels:
+            direction = rel.get("direction", "")
+            rel_type = rel.get("relationship", rel.get("type", ""))
+            target = rel.get("target_name", rel.get("target_id", ""))
+            parts.append(f"  {direction} {rel_type} -> {target}")
+
+    recent = result.get("recent_episodes", [])
+    if recent:
+        parts.append(f"\n--- Recent Episodes ({len(recent)}) ---")
+        for ep in recent:
+            ep_type = ep.get("episode_type", "")
+            created = ep.get("created_at", "")
+            snippet = (ep.get("content", "")[:100] + "...") if ep.get("content") else ""
+            parts.append(f"  [{ep_type}] {created}")
+            if snippet:
+                parts.append(f"    {snippet}")
+
+    return "\n".join(parts)
+
+
+@mcp.tool()
+async def entity_edges(
+    entity_id: str,
+    tenant_id: str | None = None,
+) -> str:
+    """Get all relationships (edges) for an entity in the knowledge graph.
+
+    Parameters
+    ----------
+    entity_id:
+        The unique identifier of the entity.
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    """
+    params: dict[str, Any] = {}
+    if tenant_id:
+        params["tenant_id"] = tenant_id
+
+    result = await _request("GET", f"/v1/entities/{entity_id}/edges", params=params)
+
+    edges = result.get("edges", result.get("items", []))
+    if not edges:
+        return f"No relationships found for entity {entity_id}."
+
+    parts: list[str] = [f"Found {len(edges)} relationship(s):\n"]
+    for edge in edges:
+        rel = edge.get("relationship", edge.get("type", "unknown"))
+        source = edge.get("source_name", edge.get("source_id", ""))
+        target = edge.get("target_name", edge.get("target_id", ""))
+        confidence = edge.get("confidence", "")
+        fact = edge.get("fact", "")
+        line = f"  {source} --[{rel}]--> {target}"
+        if confidence:
+            line += f" (confidence: {confidence})"
+        parts.append(line)
+        if fact:
+            parts.append(f"    Fact: {fact}")
+    return "\n".join(parts)
+
+
+@mcp.tool()
+async def entity_link(
+    source_entity_id: str,
+    target_entity_id: str,
+    relationship: str,
+    fact: str = "",
+    confidence: float = 0.8,
+    tenant_id: str | None = None,
+) -> str:
+    """Create a relationship between two entities in the knowledge graph.
+
+    Parameters
+    ----------
+    source_entity_id:
+        ID of the source entity.
+    target_entity_id:
+        ID of the target entity.
+    relationship:
+        Relationship type (e.g. "DEPENDS_ON", "OWNS", "RELATED_TO").
+    fact:
+        Human-readable description of the relationship.
+    confidence:
+        Confidence score from 0.0 to 1.0 (default 0.8).
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    """
+    body: dict[str, Any] = {
+        "source_entity_id": source_entity_id,
+        "target_entity_id": target_entity_id,
+        "relationship": relationship,
+        "fact": fact,
+        "confidence": confidence,
+    }
+    if tenant_id:
+        body["tenant_id"] = tenant_id
+
+    result = await _request("POST", "/v1/link", json_body=body)
+
+    link_id = result.get("id", "unknown")
+    return f"Link created. ID: {link_id}"
+
+
+# ===========================================================================
+# TOOLS — Admin & Observability
+# ===========================================================================
+
+
+@mcp.tool()
+async def health_check() -> str:
+    """Check CortexDB server health status."""
+    result = await _request("GET", "/v1/admin/health")
+    return json.dumps(result, indent=2)
+
+
+@mcp.tool()
+async def get_usage(
+    tenant_id: str | None = None,
+) -> str:
+    """Get current usage statistics and tier limits.
+
+    Shows memory count, recall calls, and how close you are to tier limits.
+
+    Parameters
+    ----------
+    tenant_id:
+        Tenant scope (uses API key's default tenant if omitted).
+    """
+    result = await _request("GET", "/v1/admin/usage")
+
+    tier = result.get("tier", "unknown")
+    usage = result.get("usage", {})
+    limits = result.get("limits", {})
+
+    mem = usage.get("memories", {})
+    recalls = usage.get("recalls", {})
+
+    parts: list[str] = [
+        f"Tier: {tier}",
+        "",
+        "Memories:",
+        f"  Total: {mem.get('total', 0):,}",
+        f"  Limit: {limits.get('max_memories', 'unknown')}",
+        f"  Utilization: {mem.get('utilization_pct', 0):.1f}%",
+        "",
+        "Recall Calls (this month):",
+        f"  Used: {recalls.get('this_month', 0):,}",
+        f"  Limit: {limits.get('max_recalls_per_month', 'unknown')}",
+        f"  Utilization: {recalls.get('utilization_pct', 0):.1f}%",
+        "",
+        f"Entities: {usage.get('entities_count', 0):,}",
+        f"Lifetime recalls: {recalls.get('lifetime', 0):,}",
+    ]
+    return "\n".join(parts)
+
+
+@mcp.tool()
+async def get_insights(
+    tenant_id: str | None = None,
+) -> str:
+    """Generate proactive insights from CortexDB episodes.
+
+    Analyzes stored episodes to surface actionable intelligence such as
+    incident spikes, new dependencies, knowledge gaps, deployment risks,
+    stale documentation, and recurring issues.
+
+    Parameters
+    ----------
+    tenant_id:
+        Tenant scope for multi-tenant deployments.
+    """
+    engine = InsightsEngine(
+        cortex_url=_config.url,
+        api_key=_config.api_key,
+        tenant_id=tenant_id,
+    )
+    insights = await engine.generate_all()
+
+    if not insights:
+        return "No insights generated. Everything looks stable."
+
+    parts: list[str] = [f"Generated {len(insights)} insight(s):\n"]
+    for insight in insights:
+        severity_tag = f"[{insight.severity.value.upper()}]"
+        parts.append(f"{severity_tag} {insight.title}")
+        parts.append(f"  {insight.description}")
+        if insight.entities:
+            parts.append(f"  Entities: {', '.join(insight.entities)}")
+        parts.append("")
+
+    return "\n".join(parts)
+
+
+@mcp.tool()
+async def get_ontology() -> str:
+    """Get the entity types and relationship types known to CortexDB.
+
+    Useful for understanding what kinds of entities and relationships
+    exist in the knowledge graph.
+    """
+    types_result = await _request("GET", "/v1/admin/ontology/types")
+    rels_result = await _request("GET", "/v1/admin/ontology/relationships")
+
+    entity_types = types_result.get("entity_types", [])
+    rel_types = rels_result.get("relationship_types", [])
+
+    parts: list[str] = [f"Entity Types ({len(entity_types)}):\n"]
+    for et in entity_types:
+        name = et.get("name", "")
+        desc = et.get("description", "")
+        parts.append(f"  {name}: {desc}" if desc else f"  {name}")
+
+    parts.append(f"\nRelationship Types ({len(rel_types)}):\n")
+    for rt in rel_types:
+        name = rt.get("name", "")
+        desc = rt.get("description", "")
+        parts.append(f"  {name}: {desc}" if desc else f"  {name}")
+
+    return "\n".join(parts)
+
+
+@mcp.tool()
+async def export_data(
+    tenant_id: str | None = None,
+    format: str = "json",
+) -> str:
+    """Export memories from CortexDB.
+
+    Parameters
+    ----------
+    tenant_id:
+        Tenant scope (exports all data for this tenant).
+    format:
+        Export format: "json" (default).
+    """
+    body: dict[str, Any] = {"format": format}
+    if tenant_id:
+        body["tenant_id"] = tenant_id
+
+    result = await _request("POST", "/v1/export", json_body=body)
+
+    count = result.get("episode_count", result.get("count", 0))
+    export_id = result.get("export_id", "")
+    return f"Export complete. {count} episodes exported. Export ID: {export_id}"
+
+
+@mcp.tool()
+async def import_data(
+    data: str,
+    tenant_id: str | None = None,
+    format: str = "json",
+) -> str:
+    """Import memories into CortexDB.
+
+    Parameters
+    ----------
+    data:
+        JSON string of episodes to import.
+    tenant_id:
+        Tenant scope for the imported data.
+    format:
+        Import format: "json" (default).
+    """
+    body: dict[str, Any] = {"data": data, "format": format}
+    if tenant_id:
+        body["tenant_id"] = tenant_id
+
+    result = await _request("POST", "/v1/import", json_body=body)
+
+    imported = result.get("imported", result.get("count", 0))
+    return f"Import complete. {imported} episodes imported."
+
+
+# ===========================================================================
+# RESOURCES
+# ===========================================================================
+
+
+@mcp.resource("cortexdb://health")
+async def health_resource() -> str:
+    """CortexDB server health status."""
+    result = await _request("GET", "/v1/admin/health")
+    return json.dumps(result, indent=2)
+
+
+@mcp.resource("cortexdb://metrics")
+async def metrics_resource() -> str:
+    """CortexDB server metrics (requests, errors, rate limits)."""
+    try:
+        result = await _request("GET", "/v1/admin/metrics")
+        return json.dumps(result, indent=2)
+    except RuntimeError:
+        return json.dumps({"error": "Metrics endpoint unavailable."})
+
+
+@mcp.resource("cortexdb://usage")
+async def usage_resource() -> str:
+    """Current usage statistics and tier limits."""
+    try:
+        result = await _request("GET", "/v1/admin/usage")
+        return json.dumps(result, indent=2)
+    except RuntimeError:
+        return json.dumps({"error": "Usage endpoint unavailable."})
+
+
+@mcp.resource("cortexdb://episodes")
+async def episodes_resource() -> str:
+    """Recent episodes stored in CortexDB (last 50)."""
+    try:
+        result = await _request(
+            "GET", "/v1/episodes", params={"limit": 50, "offset": 0}
+        )
+        episodes = result.get("episodes", result.get("items", []))
+        return json.dumps(episodes, indent=2)
+    except RuntimeError:
+        return json.dumps({"error": "Episodes endpoint unavailable."})
+
+
+@mcp.resource("cortexdb://entities")
+async def entities_resource() -> str:
+    """Entities in the CortexDB knowledge graph (top 100)."""
+    try:
+        result = await _request("GET", "/v1/entities", params={"limit": 100})
+        entities = result.get("entities", result.get("items", []))
+        return json.dumps(entities, indent=2)
+    except RuntimeError:
+        return json.dumps({"error": "Entities endpoint unavailable."})
+
+
+@mcp.resource("cortexdb://insights")
+async def insights_resource() -> str:
+    """Proactive insights generated from stored episodes."""
+    engine = InsightsEngine(
+        cortex_url=_config.url,
+        api_key=_config.api_key,
+    )
+    try:
+        insights = await engine.generate_all()
+        return json.dumps([i.to_dict() for i in insights], indent=2)
+    except Exception as exc:
+        return json.dumps({"error": str(exc)})
+
+
+@mcp.resource("cortexdb://ontology")
+async def ontology_resource() -> str:
+    """Entity types and relationship types in the knowledge graph schema."""
+    try:
+        types_result = await _request("GET", "/v1/admin/ontology/types")
+        rels_result = await _request("GET", "/v1/admin/ontology/relationships")
+        return json.dumps({
+            "entity_types": types_result.get("entity_types", []),
+            "relationship_types": rels_result.get("relationship_types", []),
+        }, indent=2)
+    except RuntimeError:
+        return json.dumps({"error": "Ontology endpoints unavailable."})
+
+
+# ===========================================================================
+# PROMPTS
+# ===========================================================================
+
+
+@mcp.prompt()
+def investigate_incident(topic: str) -> str:
+    """Investigate an incident using CortexDB memory.
+
+    Parameters
+    ----------
+    topic:
+        The incident or topic to investigate.
+    """
+    return (
+        f"Given the context from CortexDB, investigate this incident: {topic}\n\n"
+        "Steps:\n"
+        "1. Search CortexDB for all memories related to the incident.\n"
+        "2. Identify the timeline of events.\n"
+        "3. Determine root cause based on available evidence.\n"
+        "4. Suggest remediation steps.\n"
+    )
+
+
+@mcp.prompt()
+def summarize_knowledge(topic: str) -> str:
+    """Summarize everything CortexDB knows about a topic.
+
+    Parameters
+    ----------
+    topic:
+        The topic to summarize knowledge for.
+    """
+    return (
+        f"Summarize everything CortexDB knows about: {topic}\n\n"
+        "Include:\n"
+        "- Key facts and relationships\n"
+        "- Timeline of relevant events\n"
+        "- Confidence levels for each piece of information\n"
+        "- Any gaps in knowledge\n"
+    )
+
+
+@mcp.prompt()
+def deployment_review(service: str) -> str:
+    """Pre-deployment review using CortexDB memory.
+
+    Parameters
+    ----------
+    service:
+        The name of the service being deployed.
+    """
+    return (
+        f"Perform a deployment review for service: {service}\n\n"
+        "Using CortexDB memory, evaluate:\n"
+        "1. Recent incidents or outages related to this service.\n"
+        "2. Dependencies and downstream consumers that may be affected.\n"
+        "3. Configuration changes in the last 7 days.\n"
+        "4. Open issues or known risks flagged in previous deployments.\n"
+        "5. Rollback plan — is there a safe previous version?\n\n"
+        "Provide a go/no-go recommendation with supporting evidence.\n"
+    )
+
+
+@mcp.prompt()
+def onboard_to_codebase(repo: str) -> str:
+    """Onboard to a codebase using CortexDB's stored knowledge.
+
+    Parameters
+    ----------
+    repo:
+        The repository or project name.
+    """
+    return (
+        f"Help me understand the {repo} codebase using CortexDB.\n\n"
+        "Please:\n"
+        "1. Search for architecture decisions and design documents.\n"
+        "2. List the key entities (services, modules, teams).\n"
+        "3. Show dependency relationships from the knowledge graph.\n"
+        "4. Summarize recent changes and ongoing work.\n"
+        "5. Highlight any known issues or technical debt.\n"
+    )
+
+
+@mcp.prompt()
+def weekly_digest(tenant_id: str | None = None) -> str:
+    """Generate a weekly activity digest from CortexDB.
+
+    Parameters
+    ----------
+    tenant_id:
+        Optional tenant scope.
+    """
+    scope = f" for tenant {tenant_id}" if tenant_id else ""
+    return (
+        f"Generate a weekly digest{scope} from CortexDB.\n\n"
+        "Include:\n"
+        "1. Summary of all episodes ingested this week (by type and source).\n"
+        "2. New entities discovered.\n"
+        "3. Key decisions and their context.\n"
+        "4. Incidents and their current status.\n"
+        "5. Proactive insights and recommendations.\n"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    """Run the CortexDB MCP server over stdio transport."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()