Skip to main content
Glama
truongtnn404

gpkg-mcp

by truongtnn404
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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

Related MCP server: kg-memory-mcp

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).

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • code-graph-mcp

    sdsrss
    A
    license
    Not graded
    quality
    A
    maintenance
    A high-performance code knowledge graph server implementing MCP, indexing codebases into a structured AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing.
    3,783 npm
    75
    MIT

  • kg-memory-mcp

    arunmenon
    F
    license
    Not graded
    quality
    D
    maintenance
    An in-memory knowledge graph MCP server that gives coding agents structural and semantic recall over codebases by indexing Python source, ADR documents, and project configuration, exposing 7 tools for search, traversal, context retrieval, and natural-language Q&A.
    -

  • Neo4j MCP Server

    alvaropaco
    A
    license
    A
    quality
    B
    maintenance
    MCP server for Neo4j that provides abstract graph operations for LLMs, enabling safe and consistent interaction with Neo4j databases through tools like search, insert, update, delete, and schema introspection.
    8
    MIT