Skip to content

MCP Server Implementation #11

@tfius

Description

@tfius

Parent: #10 (EPIC: Transform DataCortex into Context Engine)
Priority: HIGH | Phase: 2 - Connectivity | Complexity: Large

What to Implement

Create a Model Context Protocol (MCP) server that exposes DataCortex capabilities to any MCP-compatible AI agent (Claude, Cursor, etc.).

MCP Capabilities to Expose

1. Resources (Read-only data access):

  • graph://nodes - List all nodes in the knowledge graph
  • graph://nodes/{id} - Get specific node with content
  • graph://clusters - Get cluster information
  • graph://tags - Get all tags with counts
  • pulse://latest - Get latest pulse snapshot
  • pulse://history - Get pulse change history

2. Prompts (Pre-built context generators):

  • summarize-project - Summarize context for a specific project/topic
  • find-experts - Find experts on a topic based on contribution patterns
  • decision-history - Get decision history for a topic
  • knowledge-gaps - Identify gaps in knowledge around a topic

3. Tools (Actions agents can invoke):

  • search_graph - Semantic search across knowledge graph
  • get_neighbors - Get related nodes within N hops
  • find_path - Find connection path between two nodes
  • log_decision - Record a new decision trace
  • suggest_links - Get link suggestions for a node

How to Implement

File Structure

src/datacortex/mcp/
├── __init__.py
├── server.py          # Main MCP server implementation
├── resources.py       # Resource handlers
├── prompts.py         # Prompt templates
├── tools.py           # Tool implementations
└── protocol.py        # MCP protocol utilities

Step 1: Add MCP Dependencies

# pyproject.toml
dependencies = [
    ...
    "mcp>=0.1.0",  # Model Context Protocol SDK
]

Step 2: Create MCP Server Base

# src/datacortex/mcp/server.py
from mcp.server import Server
from mcp.types import Resource, Tool, Prompt

class DatacortexMCPServer:
    def __init__(self, config: DatacortexConfig):
        self.config = config
        self.server = Server("datacortex")
        self._register_handlers()

    def _register_handlers(self):
        @self.server.list_resources()
        async def list_resources() -> list[Resource]:
            return [
                Resource(uri="graph://nodes", name="Knowledge Graph Nodes"),
                Resource(uri="graph://clusters", name="Graph Clusters"),
            ]

        @self.server.list_tools()
        async def list_tools() -> list[Tool]:
            return [
                Tool(
                    name="search_graph",
                    description="Semantic search across knowledge graph",
                    inputSchema={
                        "type": "object",
                        "properties": {
                            "query": {"type": "string"},
                            "limit": {"type": "integer", "default": 10}
                        },
                        "required": ["query"]
                    }
                ),
            ]

Step 3: Implement Resource Handlers

# src/datacortex/mcp/resources.py
async def get_graph_nodes(uri: str) -> str:
    config = load_config()
    graph = build_graph(config)
    return json.dumps([n.model_dump() for n in graph.nodes])

Step 4: Implement Tool Handlers

# src/datacortex/mcp/tools.py
async def search_graph(query: str, limit: int = 10) -> dict:
    results = search_documents(query, top_k=limit)
    return {"results": [r.model_dump() for r in results]}

Step 5: Add CLI Command

@cli.command()
@click.option('--transport', type=click.Choice(['stdio', 'sse']), default='stdio')
@click.option('--port', default=8766)
def mcp(transport: str, port: int):
    """Start the MCP server for AI agent integration."""
    server = DatacortexMCPServer(load_config())
    if transport == 'stdio':
        server.run_stdio()
    else:
        server.run_sse(port=port)

Acceptance Criteria

  • MCP server starts with datacortex mcp
  • All resources accessible via MCP protocol
  • Tools execute correctly and return structured data
  • Server works with Claude Desktop and other MCP clients
  • Documentation added for MCP setup

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions