Project Knowledge MCP Server

An MCP server that builds and serves structured knowledge about projects in a GitLab group.

It runs in a single OS process and exposes two surfaces:

• MCP over stdio — eight tools that an MCP client can call to query projects and trigger refreshes.

• Read-only HTML visualization on http://127.0.0.1:{port} — diagrams of project profiles, shared dependencies, and purpose conflicts.

Both surfaces read from the same Knowledge_Store (a single SQLite file with snapshot-based atomic-pointer-swap semantics) so readers always see a consistent view, even while a refresh is in flight.

What does the analysis? Static inspection in Python (no LLM). For every project, four sub-analyzers run: purpose (READMEs, GitLab description, manifests, top-level docstrings), I/O extractor (HTTP routes, scheduled tasks, message consumers/publishers, file I/O, CLI entrypoints), external services (HTTP clients, brokers, object stores), and database tables (SQL/ORM references, read/write modes). Source code is fetched at the configured Analysis_Branch (default uat).

Go analyzer support

Go repositories are analyzed in-process with the same depth as Python, JavaScript/TypeScript, and Java repositories. No Go toolchain is invoked at runtime; a hand-written Python tokenizer reads .go source directly. The Go layer activates automatically when a RepositoryContents snapshot contains at least one .go file or a repo-root go.mod — there is no configuration to enable.

What gets detected

What gets excluded

• Vendor directories. Any .go file whose path contains a directory segment named vendor is skipped end-to-end. The Go scanners reject vendored paths at the parser boundary, and the language-agnostic detectors are also handed a vendor-aware view so vendored Go source's embedded string literals cannot leak into SQL, URL, or SDK-pattern detections.

• Build-constraint-gated files. A file with a non-trivial //go:build or // +build line (e.g. linux && amd64, darwin, !cgo) is wholesale skipped because honoring the constraint requires a Go toolchain. Skipped files are surfaced in degraded_sections as "<section>: skipped <path> (build constraint requires toolchain)".

• cgo files. A file containing import "C" is skipped for the same reason and surfaced under the same degraded_sections shape with reason cgo directive requires toolchain.

• Tokenization errors. Unterminated strings, raw strings, block comments, and invalid escape sequences are contained per file: the affected file contributes zero detections and is surfaced with reason tokenization failed: <detail>.

• DI and config noise. fx.New / fx.Provide / fx.Invoke / fx.Module / fx.Hook / *fx.Lifecycle calls describe internal wiring and never produce HTTP, scheduler, ActiveMQ, file-I/O, CLI, or external-service detections by themselves. viper configuration reads (*viper.Viper.GetString, SetConfigName, AddConfigPath, etc.) never contribute to the purpose summary or any detection.

Triggering Go analysis

No flag, no environment variable, no client opt-in. Run the server as documented above against a GitLab group containing Go projects — every refresh that fetches a snapshot with .go files or a go.mod automatically routes through the Go sub-analyzers. The result is observable through the same MCP tools and visualization routes as any other project:

• get_project_purpose returns a summary derived from go.mod / package doc when no README is present.

• get_project_io lists HTTP routes, cron schedules, ActiveMQ destinations, file I/O, and binary entry points found in the Go source.

• get_project_dependencies lists fec_pool_service (when reached via either pb or dbadapter), ActiveMQ brokers, and any URL-literal-derived service, plus the database tables extracted from in-process SQL.

When a Go file is skipped for any reason listed above, the affected section name appears in the profile's degraded_sections list with a structured "<section>: skipped <path> (<reason>)" entry so the operator can see exactly which files the analyzer could not reach.

Related MCP server: ontomics

Requirements

• Python 3.11+

• A GitLab access token with read_api and read_repository scopes for the target group.

Install

From this repository:

pip install -e ".[dev]"

The install registers a console script:

project-knowledge-mcp = project_knowledge_mcp.main:main

Configuration

Configuration is read from environment variables. On any missing or invalid value the server prints a single line to stderr that names the offending key and exits non-zero before either surface accepts traffic.

The store persists across restarts: on reopen, readers immediately serve the last successfully committed snapshot, and an in-flight job aborted at shutdown does not affect that pointer.

Run

GITLAB_BASE_URL=https://gitlab.example.com \
GITLAB_GROUP_PATH=acme/platform \
GITLAB_ACCESS_TOKEN=glpat-... \
project-knowledge-mcp

On startup you will see a single log line:

Visualization_Server ready at http://127.0.0.1:7345

The MCP server simultaneously speaks JSON-RPC over stdin/stdout, so this command is normally launched by an MCP client rather than run interactively.

Use from an MCP client

Configure your MCP-aware tool (Claude Desktop, an editor MCP integration, etc.) to spawn the server. Example config:

{
  "mcpServers": {
    "project-knowledge": {
      "command": "project-knowledge-mcp",
      "env": {
        "GITLAB_BASE_URL": "https://gitlab.example.com",
        "GITLAB_GROUP_PATH": "acme/platform",
        "GITLAB_ACCESS_TOKEN": "glpat-...",
        "ANALYSIS_BRANCH": "uat",
        "REFRESH_INTERVAL": "1h"
      }
    }
  }
}

Available MCP tools

Eight tools are registered. The first six are read-only; the last two trigger ingestion.

Refresh tools enforce a single-flight rule: while one ingestion job is running, additional refresh requests (from any source — tool call or scheduler) are rejected with the message Ingestion_Job is already in progress. The Knowledge_Store is unchanged.

Out-of-scope project ids return a tool result with isError: true and the message project {id} is not in scope.

Visualization

Browse http://127.0.0.1:7345/ (or your configured port). All routes serve text/html; charset=utf-8:

Enable graph rendering

The /dependencies page renders an interactive knowledge graph using Cytoscape.js. Drop the bundle at src/project_knowledge_mcp/static/cytoscape.min.js:

curl -L -o src/project_knowledge_mcp/static/cytoscape.min.js \
  https://cdn.jsdelivr.net/npm/cytoscape@3/dist/cytoscape.min.js

When Cytoscape is loaded the page emits an interactive node-and-edge graph with zoom, pan, drag, and hover tooltips. The same diagram is also emitted as a Mermaid <pre class="mermaid"> block; when cytoscape.min.js is absent the page falls back to Mermaid by dropping a Mermaid bundle at src/project_knowledge_mcp/static/mermaid.min.js:

curl -L -o src/project_knowledge_mcp/static/mermaid.min.js \
  https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js

For air-gapped networks, fetch either file from any machine that can reach the CDN and copy it into the same path. See src/project_knowledge_mcp/static/README.md for details. When both files are missing the pages still load — graphs degrade to the raw graph LR ... text.

Behavior pinned by the spec:

• Reads happen at request time — no in-memory caching of profiles.

• Non-matching paths → 404 with the requested path echoed in the body.

• Non-GET methods → 405 with Allow: GET.

• Knowledge_Store failures → 503 with no profile-derived content.

• Every successful response begins within 5 seconds.

Typical workflow

1. Start the server with REFRESH_INTERVAL=1h (or trigger refreshes manually).

2. After the first ingestion completes, the visualization populates and the MCP query tools start returning data.

3. Iterate: as code in your GitLab projects evolves on Analysis_Branch, each refresh produces a new snapshot. Readers atomically switch to the new snapshot only when the ingestion commits.

Operations

• Skipped projects. When a project has no Analysis_Branch, the ingestion records a skip with reason analysis_branch_missing and continues with the rest. No Project_Profile is produced for skipped projects; they still appear in the catalog so you can tell "in scope but not yet analyzed" from "out of scope".

• Auth failures. A 401/403 from GitLab aborts the in-flight job and surfaces the status code; the previous snapshot remains current. A 404 for the configured group raises GitLabGroupNotFoundError(group_path).

• Shutdown. SIGTERM/SIGINT triggers a documented shutdown ordering: stop accepting new HTTP connections → close MCP stdio → mark any in-flight snapshot failed (the current_snapshot pointer is unchanged) → flush and close the SQLite store → exit.

• Port already in use. Startup prints startup error: visualization.port {port} is already in use and exits non-zero.

Tests

pytest -m unit         # ~3s
pytest -m property     # Hypothesis, max_examples=100, ~30s
pytest -m integration  # subprocess + HTTP + SQLite, ~15s

Or all of them:

pytest

Project layout

src/project_knowledge_mcp/
  config.py              # env loader + validator (single termination path)
  errors.py              # error type hierarchy
  models.py              # Project_Profile, EnumeratedProject, ConflictResult, ...
  knowledge_store.py     # SQLite + snapshot pointer + WAL
  project_catalog.py     # snapshot-scoped in-scope set
  gitlab_connector.py    # paginated GitLab API client
  project_analyzer/      # purpose, io_extractor, external_services, db_tables
  conflict_detector.py   # classify_pair + find_all_conflicts
  ingestion_coordinator.py  # single-flight state machine
  scheduler.py           # periodic refresh
  mcp_server.py          # MCP over stdio + 8 tools
  visualization_server.py   # Starlette + Uvicorn (loopback only)
  diagram_renderer.py    # Jinja2 + inline Mermaid
  main.py                # wiring, startup, shutdown ordering

The full specification (requirements, design, and the 30 correctness properties the implementation is verified against) lives under .kiro/specs/project-knowledge-mcp/.