[Feature] MCP server for Elder relationship and resource lookups

[PenguinzTech]

User Story

As an AI agent or LLM-powered workflow, I want to query Elder's infrastructure knowledge graph via a Model Context Protocol (MCP) server so that I can resolve resource relationships, find similar infrastructure, and surface discovery data without writing custom API clients.

Background

Elder discovers and maps cloud/Kubernetes infrastructure. Once the pgvector + graph layer is in place (see #91), the data becomes semantically queryable. An MCP server surfaces this as structured tools that any MCP-compatible AI agent (Claude, GPT-4, etc.) can call directly — no custom integration needed.

Proposed MCP Server

Location

services/mcp-server/ — standalone Python service, deployed as its own container

Transport

• stdio (default, for local agent use)
• HTTP/SSE (optional, for remote agent access) — expose on port 8765

Tools Exposed

Tool	Description	Input	Output
list_entities	List discovered resources filtered by type/provider/region	{type?, provider?, region?, limit}	[Entity]
get_entity	Fetch full details of a resource by ID	{entity_id}	Entity
find_relationships	Return neighbors of a resource (graph traversal)	{entity_id, depth?, rel_type?}	[Relationship]
search_similar	Semantic search using vector embedding	{query: str, k?, type?}	[Entity]
get_network_topology	Return VPCs, subnets, LBs and their entity mappings	{provider?, region?}	NetworkTopology
list_services	List K8s/Lambda services and their dependencies	{namespace?, provider?}	[Service]
get_identity_access	List IAM/ServiceAccount roles for an entity	{entity_id}	[Identity]
summarize_environment	High-level stats: counts by type/provider/region	{}	EnvironmentSummary

Resources Exposed (MCP Resources)

• elder://entities/{id} — individual resource by ID
• elder://topology/{provider}/{region} — network topology snapshot
• elder://services/{namespace} — services in a K8s namespace

Prompts Exposed

• elder_audit_prompt — generates an infrastructure audit prompt from current discovery data
• elder_dependency_prompt — generates a dependency analysis prompt for a given entity

Implementation

• Python 3.13, mcp SDK (pip install mcp)
• Talks to Elder Flask API via HTTP (not direct DB) — MCP server is a thin API client
• Auth: Bearer token via ELDER_API_TOKEN env var
• Configurable via env vars: ELDER_API_URL, ELDER_API_TOKEN, MCP_TRANSPORT (stdio|http)
• Dockerfile: python:3.13-slim-bookworm base, SHA256-pinned
• K8s: Helm + Kustomize deployment (sidecar or standalone pod)

Acceptance Criteria

• services/mcp-server/ created with standalone Python MCP server
• All 8 tools implemented and returning typed responses
• MCP Resources for entities, topology, services
• 2 Prompt templates implemented
• stdio and HTTP/SSE transports working
• Unit tests for all tools (≥90% coverage, mocked API client)
• Integration test: Claude Desktop config connects and lists entities
• Dockerfile builds successfully (python:3.13-slim-bookworm, SHA256-pinned)
• Helm chart and Kustomize overlay added for mcp-server
• ELDER_API_URL, ELDER_API_TOKEN, MCP_TRANSPORT env vars documented
• docs/MCP_SERVER.md with setup guide and example Claude Desktop config
• Linting passes
• Security scan passes

Notes

• Depends on [Feature] Migrate to pgvector + graph-backed relationship model for AI-ready data layer #91 for search_similar and find_relationships tools; other tools work with current API
• MCP SDK: https://github.com/modelcontextprotocol/python-sdk
• Claude Desktop config example to include in docs:

  {
    "mcpServers": {
      "elder": {
        "command": "python3",
        "args": ["-m", "elder_mcp"],
        "env": { "ELDER_API_URL": "http://localhost:8080", "ELDER_API_TOKEN": "..." }
      }
    }
  }