Kernel Subsystems — Core Engines
Docs » Kernel Subsystems — Core Engines » MCP Server Package
Raw .md

MCP Server Package

Status: Active
Purpose: Model Context Protocol (MCP) server implementation for zqk

Overview

This package provides a complete MCP server implementation that enables AI assistants and other MCP clients to interact with the zqk knowledge kernel through a standardized protocol. The server exposes graph traversal tools that allow programmatic access to the graph backend.

Architecture

Components

  • server.go: Core MCP server implementation with JSON-RPC protocol handling
  • handlers_graph.go: Graph traversal tool handlers
  • graph_connection.go: Graph backend connection management
  • tools.go: Tool registration and schema definitions
  • cli_bridge.go: CLI command discovery and MCP tool generation with privilege filtering
  • handlers_graph_test.go: Comprehensive test suite for graph tools
  • cli_bridge_test.go: Test suite for CLI bridge functionality
  • cli_bridge_privilege_test.go: Comprehensive privilege validation tests

Note: Metrics tools (PCS, EDD, D&B) are exposed via CLI commands and automatically available through the CLI bridge. No separate metrics bridge is needed.

Graph Traversal Tools

The MCP server exposes three graph traversal tools:

  1. graph_traversal: Perform multi-hop graph traversal starting from a node
  2. resolve_references: Resolve object references to actual graph nodes
  3. state_aware_query: Perform queries aware of object lifecycle states

CLI Bridge

The MCP server automatically exposes CLI commands as MCP tools with context-driven, security-aware filtering:

  • Automatic Discovery: Discovers all CLI commands from the cobra command tree
  • Privilege Filtering: Filters commands based on security context (roles and permissions)
  • Tool Generation: Converts cobra commands to MCP tools automatically
  • Security Context: Initializes from MCP client info during initialization

See Quickstart / MCP Integration for detailed information.

Server Shutdown and OS Signal Handling

The MCP server gracefully handles termination to prevent data loss or corrupted states:

  • OS Signals: The server listens for SIGINT and SIGTERM. When received, it initiates a graceful shutdown sequence.
  • Shutdown Tool: Clients can request a graceful shutdown via the server_shutdown tool.
  • Graceful Shutdown: The shutdown sequence flushes remaining messages, stops receiving new events, and safely closes active resource handles.

Documentation

Detailed MCP integration documentation is available in:

Metrics Tools

Metrics tools (PCS, EDD, D&B) are exposed via the CLI bridge:

  • CLI Commands: Metrics are accessed through CLI commands (e.g., zqk reports pcs, zqk reports edd, zqk reports blockers)
  • Automatic MCP Exposure: The CLI bridge automatically exposes these commands as MCP tools
  • No Special Bridge Needed: Metrics tools use the same CLI bridge pattern as all other commands
  • Consistent Architecture: All functionality is exposed through CLI commands, which are automatically available via MCP

Server Execution Models: Direct Stdio vs. Proxy Adapter

ZQK supports two distinct deployment models for MCP integration with IDEs (Cursor, VS Code, Windsurf, Claude Desktop):

+-----------------------------------------------------------------------------------+
| 1. Direct Stdio (Canonical Default for Core Kernel & All Standalone Projects)     |
|                                                                                   |
|  [ IDE (Cursor / VS Code) ] --(stdio JSON-RPC)--> [ bin/zqk mcp serve ]           |
|                                                                                   |
|  * 100% self-contained within workspace (${workspaceFolder})                      |
|  * Zero background daemons, zero TCP ports, zero loopback collision hazards      |
|  * Multiple projects run in parallel with completely isolated memory & WAL       |
+-----------------------------------------------------------------------------------+

+-----------------------------------------------------------------------------------+
| 2. Proxy Adapter (Specialized for Studio Swarms & Continuous Hot-Rebuilds)        |
|                                                                                   |
|  [ IDE (Cursor) ] --(stdio)--> [ bin/zqk-mcp-ide-adapter ]                       |
|                                       |                                           |
|                               (TCP 127.0.0.1:8443)                                |
|                                       v                                           |
|                           [ zqk mcp daemon --tcp ]                                |
|                                                                                   |
|  * Shields Cursor from turning red when the underlying binary is recompiled       |
|  * Auto-reconnects when the background daemon cycles                              |
|  * Requires central daemon management; potential port clash if multiple repos    |
+-----------------------------------------------------------------------------------+

When to Use Direct Stdio (zqk mcp serve) — The Core Kernel Default

  • Default for all project-agnostic repositories: Whenever you initialize ZQK in a project or work with the core kernel, use direct stdio (bin/zqk mcp serve).
  • Why:
  • Standard MCP compliance (Anthropic specification).
  • No background daemon lifecycle to supervise or troubleshoot.
  • Zero open TCP ports, avoiding port 8443 clashes when multiple repos are open simultaneously.
  • Managed cleanly by the IDE process tree: starts on workspace open, terminates on workspace close.

When to Use Proxy Adapter (zqk mcp cursor-adapter / mcp proxy)

  • Specialized for Continuous Autonomous Swarms: Use only in dedicated development environments where autonomous agents or developers are continuously recompiling the CLI binary (go build -o bin/zqk) or cycling binaries under an active Cursor session.
  • Why: Cursor turns its MCP connector red if a direct stdio process dies. The proxy maintains a permanent, resilient stdio channel with Cursor while transparently reconnecting to the background TCP daemon whenever the daemon restarts.

Quick Start

import "github.com/zqk-os/zqk/pkg/mcp"

server := mcp.NewServer()
mcp.RegisterGraphTools(server)
server.SetRootCommand(rootCmd)
server.SetSecurityContext(secCtx)
server.Serve()

See Quickstart / MCP Integration for detailed usage examples and configuration.

Server Modes and Trimming

  • Full server (zqk mcp serve): Has the full cobra CLI tree; discovers and exposes all leaf commands as tools, plus built-in tools, prompts, and resources.
  • Alias / Curated mode (alias_mode: true in .zqk/mcp/config.yaml): Exposes a curated set of high-leverage tools (object CRUD, system status, reports, file I/O) to keep tool counts lean and well under IDE limits.

Last Updated: 2026-09-18