Skip to main content
Glama
truongtnn404

gpkg-mcp

by truongtnn404
OverviewSchemaRelated ServersScoreDiscussions
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: Neo4j GraphRAG MCP Server

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 installed

F
license - not found
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/truongtnn404/gpkg-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server