gpkg-mcp

Standalone knowledge graph MCP server for Moleculer/Go microservice projects. Scans a project directory, extracts service metadata (actions, commands, queries, routes, events, dependencies), seeds Neo4j, and exposes everything via a Python MCP server that any LLM client (Claude Desktop, Cursor, the gp-langchain bot) can call.

---

What it does

• Scans TypeScript/JavaScript Moleculer services (layered, CQRS, gateway) and Go services
• Extracts per-action metadata: handler type, params validator, ctx.call dependencies (regex + variable resolution)
• Seeds Neo4j knowledge graph and writes per-service markdown docs
• Serves a FastMCP server over Streamable HTTP or stdio
• Caches scan fingerprints with a schema_version so improved extractors always trigger a re-scan

---

Quick start (with sample data)

# One-shot bootstrap: checks prereqs, seeds sample services, starts MCP
./start.sh

The script: checks uv + Neo4j, runs uv sync, seeds sample/ data into Neo4j, then starts the server on http://localhost:8000/mcp.

---

Manual setup

cp .env.sample .env
# edit .env — set GPKG_NEO4J_URI / GPKG_NEO4J_PASSWORD at minimum

uv sync

# Scan a project
uv run gpkg scan ../my-project

# Query the knowledge graph
uv run gpkg query "payment transfer"

# Start the MCP server
uv run gpkg serve

---

Commands

Command	Description
gpkg scan <dir>	Scan all services under <dir>, seed Neo4j, write markdown KB
gpkg scan <dir> --use-llm	Enable LLM validation for low-confidence architecture detections
gpkg scan <dir> --force	Bypass fingerprint cache, rescan everything
gpkg scan <dir> --concurrency N	Set parallel scan concurrency (default: 5)
gpkg query "<text>"	Full-text query against the seeded KG
gpkg query "<text>" --service NAME	Filter results to one service
gpkg serve	Start MCP server (streamable-http on port 8000)
gpkg serve --transport stdio	Start for Claude Desktop / Cursor local use

---

MCP tools

Tool	Description
scan_project(project_dir, use_llm, force)	Scan all services; returns {scanned, seeded, skipped, failed, services}
scan_service(project_dir, service_path, use_llm)	Scan a single service; returns EnhancedServiceScanResult
query_knowledge_graph(query, service_name?)	Full-text search; returns {services, actions, relationships}
get_service(service_name)	Full stored knowledge for one service
list_services()	All known services with arch type + confidence

Resource: kb://{service_name} — the generated markdown doc for a service.

---

Configuration

Copy .env.sample to .env:

Variable	Default	Description
GPKG_NEO4J_URI	bolt://localhost:7687	Neo4j bolt URI
GPKG_NEO4J_USER	neo4j	Neo4j username
GPKG_NEO4J_PASSWORD	(empty)	Neo4j password
GPKG_KB_DIR	./knowledge_base	Markdown KB output directory
GPKG_SCAN_CONCURRENCY	5	Parallel scan workers
GPKG_LLM_ENABLED	false	Enable LLM validation pass
GPKG_LLM_MODEL	claude-haiku-4-5-20251001	Model for architecture validation
GPKG_LLM_CONFIDENCE_THRESHOLD	0.7	Only run LLM when confidence is below this
GPKG_API_KEY	(empty)	Bearer token for MCP server (empty = unauthenticated)
ANTHROPIC_API_KEY	(empty)	Required when GPKG_LLM_ENABLED=true

---

Docker

# Build
docker build -t gpkg-mcp .

# Run with a local .env and data volume
docker run --env-file .env -p 8000:8000 -v $(pwd)/knowledge_base:/data/knowledge_base gpkg-mcp

# Scan a project (mount it read-only)
docker run --env-file .env \
  -v $(pwd)/knowledge_base:/data/knowledge_base \
  -v /path/to/my-project:/project:ro \
  gpkg-mcp uv run gpkg scan /project

---

Architecture detection

Type	Detection signal
layered-moleculer	actions: block with inline handlers in start.ts or *.service.ts
cqrs-moleculer	CQRSContainer, CommandBus, QueryBus keywords
gateway-moleculer	integrate-services/ directory with RestRoute() definitions
golang-moleculer	go-moleculer in go.mod + Publisher pattern
discrete-golang-moleculer	go-moleculer in go.mod, no Publisher
external-api-service	No Moleculer; Express / Gin / Echo / Fiber

Confidence levels: high → medium → low. LLM validation runs when confidence is below GPKG_LLM_CONFIDENCE_THRESHOLD.

---

Cache schema version

knowledge/cache.py has a CACHE_SCHEMA_VERSION constant (currently 4). Bump it whenever an extractor changes — the next scan will ignore all cached fingerprints and re-scan everything.

---

Running tests

uv run pytest

Tests cover: LayeredMoleculerExtractor action/handler/call extraction, cache schema version invalidation, and MCP tool shapes (mocked store, no Neo4j needed).