mcp-probe-kit — Know the Context, Feed the Moment

---

Talk is cheap, show me the Context.

mcp-probe-kit is a protocol-level toolkit designed for developers who want AI to understand project intent, choose a precise workflow, and retain validated experience without flooding the model with internal actions.

Languages: English | 简体中文 | 日本語 | 한국어 | Español | Français | Deutsch | Português (BR)

🚀 AI-Powered Complete Development Toolkit - Covering the Entire Development Lifecycle

A powerful MCP (Model Context Protocol) server with 24 model-visible tools by default, 30 when Memory is configured, and a 34-tool compatibility surface available through MCP_TOOLSET=full. It covers the complete workflow from product analysis to final release and supports structured output.

🎉 v4 stable release: native MCP Apps, resumable plans, evidence convergence, managed GitNexus Sidecar, parent-child specs, and a version-locked CLI fallback.

Supports All MCP Clients: Cursor, Claude Desktop, Cline, Continue, and more

Protocol Support: Legacy MCP (2025-era) + Modern MCP 2026-07-28 · SDK: split TypeScript SDK v2 packages

Runtime: Node.js 20 or newer. MCP_PROTOCOL_MODE=auto is the default; use legacy or modern only for compatibility diagnosis.

---

🎬 v4 in action

v4 turns delegated Agent work into an observable and verifiable delivery loop. The animations below are rendered from the same MCP App source shipped in the npm package—not separate marketing mockups.

Feature Workbench — parent-child specs, active step, outputs, evidence, and cross-session recovery.

Memory Center — semantic search, full-content inspection, lifecycle state, evidence, stale marking, and confirmed deletion.

Convergence Gate — blocks closure when steps or requirements/spec/implementation/test/review evidence are incomplete.

• Five native MCP Apps: Memory Center, Feature Workbench, Bug Workbench, Product Workbench, and Convergence Gate.
• Resumable delegated plans: plan_heartbeat persists real progress; resume_plan restores the next executable step.
• Evidence-based convergence: converge gates delivery and long-term Memory writes.
• Managed GitNexus Sidecar: version/platform/architecture/Node isolation, integrity verification, real FTS probe, and safe degradation.
• Version-locked CLI fallback: project-local probe wrappers reach the same Tool Registry when a host drops the MCP tool lease.
• Parent-child specifications: complex releases are decomposed and recursively validated instead of being flattened into one oversized spec.

Open the five live, read-only MCP App demos

v4 stable: mcp-probe-kit@4.0.0 is the current stable release and npm latest channel.

---

📚 Complete Documentation

👉 https://mcp-probe-kit.bytezonex.com

• Quick Start - Setup in 5 minutes
• Local Memory Stack (Qdrant + Nomic Embed) - Docker Compose, ports 50008 / 50012, MCP env
• All Tools - Default, conditional Memory, App-only, and full compatibility surfaces
• Best Practices - Full development workflow guide
• v3 → v4 Migration Guide - Tool surfaces, protocol, Apps, plan state, Memory, and compatibility
• MCP Apps Live Demos - Five real read-only workbenches generated from the shipped App source

---

✨ Core Features

📦 Tool Surfaces

The default compact surface keeps every independently useful workflow while removing competing internal and maintenance entries from the model context.

• 🧭 Routing (1) — workflow
• 🔁 Plan State & Convergence (3) — plan_heartbeat, resume_plan, converge
• 🔄 Workflow Orchestration (6) — start_feature, start_bugfix, start_onboard, start_ui, start_product, start_ralph
• 📦 Project & Specification (4) — init_project, init_project_context, check_spec, estimate
• 🏗️ Architecture (1) — architecture
• 🔍 Code, Test & Git (6) — code_insight, gentest, code_review, refactor, gencommit, git_work_report
• 🎨 UI/UX Utilities (2) — ui_design_system, ui_search
• 🗣️ Structured Interview (1) — interview

That is 24 model-visible tools by default. When the full Memory stack is configured, six Memory tools are added dynamically, bringing the model-visible surface to 30:

search_memory, read_memory_asset, memorize_asset, update_memory_asset, delete_memory_asset, scan_and_extract_patterns

For compatibility and diagnostics, MCP_TOOLSET=full restores all 34 model tools. The compact surface deliberately omits add_feature, fix_bug, sync_ui_data, and ask_user: their implementations remain available through orchestration, maintenance scripts, or full compatibility mode.

workflow is a fallback tool-selection guide, not a natural-language intent classifier. The Agent normally chooses the appropriate MCP tool directly from the current conversation, Skill, and tool descriptions. scenario=auto returns guidance only (firstTool=null); an explicit scenario returns deterministic guidance for a scenario the Agent has already selected.

🔁 Delegated Plan State, Recovery, and Convergence

• Every v4 delegated plan declares executionStatePolicy and instructs the Agent to create a local checkpoint on the first step.
• plan_heartbeat persists completed/skipped steps, unresolved items, evidence, and the last verified revision under .mcp-probe-kit/plans/.
• resume_plan recalculates ready and blocked steps from stored dependencies after interruption, restart, or Agent handoff.
• converge refuses closure while steps, unresolved items, or requirements/spec/implementation/test/review evidence are incomplete. Formal long-term memory writes are allowed only after convergence passes.
• These tools track and validate Agent execution; they do not move file, shell, Git, or implementation work into the MCP server.

🛡️ Quality Constraints (single source of truth)

All hard quality rules live in one module (src/lib/quality-constraints.ts) and are injected into code_review, the add_feature task templates, and the UI tools. Change once, apply everywhere — inspired by taste-skill and impeccable.

• Code limits: single file ≤ 500 lines (split into modules/components when exceeded), function ≤ 50 lines, nesting ≤ 4, parameters ≤ 3.
• Completeness blacklist: code_review flags placeholder/elision patterns (// ..., // TODO, // rest of code, bare ...) as CRITICAL — "a partial output is a broken output".
• Anti-laziness task templates: add_feature tasks now carry a Scope-lock deliverable count, a mandatory evidence block (read code before writing), a per-file line budget, and a binary zero-tolerance rule for placeholders. check_spec validates these (missing Scope-lock = error, thin task without evidence = warning).
• UI hard red lines: numeric, machine-checkable rules — 4pt spacing scale, WCAG contrast (4.5/3/3), type scale ≥ 1.25, hero font ≤ 6rem, OKLCH, eight interaction states, cognitive load ≤ 4, motion 150-300ms.
• UI banned list + Pre-Flight checklist: match-and-refuse blacklist for AI slop (default Inter/Roboto, AI purple-blue gradients, gradient text, cookie-cutter card grids, em-dash, cream/beige body backgrounds, nested cards) plus a delivery-gate self-check matrix.

🧠 Code Graph Bridge (GitNexus)

• code_insight bridges GitNexus by default for query/context/impact analysis
• The bridge prefers an explicitly configured or system GitNexus CLI, then a version-locked managed Sidecar; GitNexus is not bundled into the main package and is never globally installed
• init_project_context bootstraps baseline graph docs under docs/graph-insights/; if docs/project-context.md already exists, it preserves the old context docs and only backfills graph docs plus the index entry
• start_feature refreshes the GitNexus index and runs task-level query/context/impact narrowing before spec generation to reduce over-scoping
• start_bugfix refreshes the GitNexus index and runs task-level graph analysis before TBP RCA to constrain failure boundary and blast radius
• Older projects that already have project-context.md but no graph docs are bootstrapped automatically through the init_project_context step
• If GitNexus is unavailable, the server falls back automatically without breaking orchestration
• Real graph queries read the .gitnexus index; docs/graph-insights/latest.md|json are readable snapshots for humans and AI agents
• MCP resources in MCP client settings list 2 entries (probe://status, probe://project/bootstrap). Graph runtime snapshots (probe://graph/latest, etc.) and probe://project/skill|agents|context|graph remain readable via resources/read when tools expose URIs
• Graph snapshots are persisted to .mcp-probe-kit/graph-snapshots (customizable via MCP_GRAPH_SNAPSHOT_DIR)
• Tool responses include _meta.graph with snapshot URI and local JSON/Markdown file paths

🐛 SRC-8 Bug Root-Cause Workflow (TBP-Inspired)

• SRC-8 Methodology (中文: src8-methodology.zh-CN.md) — Software Root-Cause 8-step protocol inspired by Toyota TBP / PDCA, adapted for code and AI agents
• start_bugfix runs graph narrowing, then delegated SRC-8 plan (metadata.plan.steps src8-1~8) before repair and tests
• fix_bug returns delegated plan (src8-1~8), src8Checklist, rootCauseWorksheet (Step 4 core), and hard gates (no code change until root-cause worksheet is closed)
• Highlights vs manufacturing TBP: repro contract, attribution layers (including agent_behavior), contributing factors, memorize_asset for cross-repo learning

Inherited from Toyota TBP: gap thinking, Plan-before-Do, no skipping to root-cause analysis, fact-based investigation, countermeasures over symptoms, evaluate then standardize.

Our elevation: genchi-genbutsu → read code/logs/repro; Step 4 worksheet; guidance-only MCP that forces discipline while the Agent executes.

🧠 Memory Retrieval

• Memory tools use Qdrant as the vector database backend
• Embedding service supports two modes:
  • ollama
  • openai-compatible

Memory tools:

• search_memory - Semantic search across the shared memory pool (optionally prefer type / tags); text output includes id, score, summary, description, and a --- content --- body (default up to 1500 chars via MEMORY_SEARCH_CONTENT_MAX_CHARS)
• memorize_asset - Persist an already validated MemoryCandidate into vector memory; for delegated workflows, call it only after converge passes
• read_memory_asset - Read full asset content by asset_id (text output includes the full content body)
• update_memory_asset - Update an existing asset by asset_id (preserves ID; content changes re-embed)
• delete_memory_asset - Delete an asset by asset_id from the shared pool
• scan_and_extract_patterns - Extract reusable patterns from code/file/directory before deciding whether to persist

Cross-repo memory pools: do not rely on source_project / source_path for shared retrieval; put file paths in content instead. Search injection hides foreign sourcePath unless MEMORY_REPO_ID matches or MEMORY_SEARCH_SHOW_SOURCE=true.

Memory backend and embedding configuration:

• Vector database: Qdrant
• Recommended local setup: Qdrant (port 50008) + Infinity / nomic-embed (port 50012) — lighter than Ollama; see Local Memory Stack guide (中文: memory-local-setup.zh-CN.md)
• Supported embedding providers:
  • ollama
  • openai-compatible (Infinity, OpenAI, etc.)
• Required environment variables for memory write/search:
  • MEMORY_QDRANT_URL
  • MEMORY_EMBEDDING_URL
  • MEMORY_EMBEDDING_MODEL
• Optional environment variables:
  • MEMORY_QDRANT_API_KEY
  • MEMORY_QDRANT_COLLECTION (default: mcp_probe_memory)
  • MEMORY_EMBEDDING_API_KEY
  • MEMORY_EMBEDDING_PROVIDER (ollama by default)
  • MEMORY_SEARCH_LIMIT (default: 3)
  • MEMORY_SUMMARY_MAX_CHARS (default: 280)
  • MEMORY_SEARCH_MIN_SCORE (default: 0 = disabled; try 0.72 for noisy pools)
  • MEMORY_SEARCH_SHOW_SOURCE (default: false)
  • MEMORY_REPO_ID (optional; show sourcePath only when sourceProject matches)
  • MEMORY_INJECTION_CONTENT_MAX_CHARS (default: 1500; max content per hit injected into start_* guides)
• Behavior notes:
  • Read-only memory access only requires MEMORY_QDRANT_URL
  • Memory write is enabled only when MEMORY_QDRANT_URL, MEMORY_EMBEDDING_URL, and MEMORY_EMBEDDING_MODEL are all configured
  • The Qdrant collection is auto-created on first write, and vector dimension is inferred from the first embedding response

Recommended local memory setup (Qdrant + Nomic Embed / Infinity):

Full Docker Compose, ports, and troubleshooting: docs/memory-local-setup.md

{
  "mcpServers": {
    "mcp-probe-kit": {
      "command": "npx",
      "args": ["-y", "mcp-probe-kit@4.0.0"],
      "env": {
        "MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
        "MEMORY_QDRANT_API_KEY": "your-qdrant-api-key",
        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:50012/embeddings",
        "MEMORY_EMBEDDING_MODEL": "nomic-ai/nomic-embed-text-v1.5",
        "MEMORY_EMBEDDING_API_KEY": "your-infinity-api-key",
        "MEMORY_SEARCH_LIMIT": "3",
        "MEMORY_SUMMARY_MAX_CHARS": "280"
      }
    }
  }
}

Alternative: Qdrant + Ollama (if you already run Ollama):

docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
ollama pull nomic-embed-text

"MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
"MEMORY_EMBEDDING_PROVIDER": "ollama",
"MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
"MEMORY_EMBEDDING_MODEL": "nomic-embed-text"

OpenAI-compatible embedding (hosted API):

{
  "mcpServers": {
    "mcp-probe-kit": {
      "command": "npx",
      "args": ["-y", "mcp-probe-kit@4.0.0"],
      "env": {
        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
        "MEMORY_EMBEDDING_URL": "https://your-embedding-endpoint/v1/embeddings",
        "MEMORY_EMBEDDING_API_KEY": "your-api-key",
        "MEMORY_EMBEDDING_MODEL": "text-embedding-3-small"
      }
    }
  }
}

🎯 Structured Output

Core and orchestration tools support structured output, returning machine-readable JSON data, improving AI parsing accuracy, supporting tool chaining and state tracking.

⏱️ Native Tasks, Progress, and Cancellation

• Uses an SDK-independent Internal Task Runtime, with the current SDK task protocol exposed through a Legacy Adapter
• Supports task lifecycle endpoints: tasks/get, tasks/result, tasks/list, tasks/cancel
• Advertises capabilities.tasks.requests.tools.call so clients can create tasks for tools/call
• Falls back to synchronous execution when protocol task storage is unavailable
• Emits notifications/progress when client provides _meta.progressToken
• Ignores late progress after terminal completion; tool/task result is the final completion signal
• Handles request cancellation via AbortSignal and preserves a clear cancelled state
• Long-running orchestration tools (start_*) and sync_ui_data support cooperative cancellation/progress callbacks
• Internal task persistence defaults to memory. Set MCP_TASK_STORE=json to use .mcp-probe-kit/tasks.json, or set MCP_TASK_STORE_PATH to choose another JSON path. Interrupted tasks that cannot reconstruct their executor are explicitly marked failed on restart instead of being reported as still running.

🔌 Official MCP Apps and Memory Center

v4.0.0 uses the official @modelcontextprotocol/ext-apps SDK and the stable io.modelcontextprotocol/ui extension.

• MCP Apps are enabled by default and can be disabled with MCP_ENABLE_UI_APPS=0.
• UI metadata and ui:// resources are exposed only after the client advertises support for text/html;profile=mcp-app.
• Five stable Apps are included: Memory Center, Feature Workbench, Bug Workbench, Product Workbench, and Convergence Gate.
• Memory Center uses a responsive master-detail layout for historical browsing, semantic search, full-content inspection, lifecycle state, evidence, stale marking, and confirmed deletion.
• Feature and Bug Workbenches render a live plan stepper. The App polls resume_plan while visible, and progress advances only after the Agent records real step state through plan_heartbeat.
• Product Workbench and Convergence Gate use the same developer-console design system for delivery paths, blockers, and evidence gaps.
• list_memory_assets is an App-only action with _meta.ui.visibility=["app"]. It may appear in the raw tools/list response of an Apps-capable host, but compliant hosts must not offer it to the model. The model-visible count remains 24 by default or 30 with Memory.
• Clients without MCP Apps support continue to receive the normal text and structuredContent responses; no GUI capability is required for existing workflows.
• Trace metadata passthrough remains available through MCP_ENABLE_EXTENSIONS_CAPABILITY=1.

🧪 Tool and Real-Agent Contract Verification

# Deterministic server-side audit across compact, Memory, full, App-only, and Legacy surfaces
npm run audit:tools

# Optional real-host audit: Claude Code calls and evaluates all 34 model tools
npm run audit:tools:agent

The direct audit verifies non-empty readable text, structuredContent, and that every referenced MCP tool exists on the active surface. The real-Agent audit additionally checks whether an Agent understands each tool, can follow the returned guidance, sees no text/structured contradiction, and can execute the stated next step. It is intentionally separate from release:verify because it requires a configured Claude Code account and incurs model usage.

🧭 Delegated Orchestration Protocol

All start_* orchestration tools return an execution plan in structuredContent.metadata.plan.
AI needs to call tools step by step and persist files, rather than the tool executing internally.

Plan Schema (Core Fields):

{
  "mode": "delegated",
  "steps": [
    {
      "id": "spec",
      "tool": "add_feature",
      "args": { "feature_name": "user-auth", "description": "User authentication feature" },
      "outputs": ["docs/specs/user-auth/requirements.md"]
    }
  ]
}

Field Description:

• mode: Fixed as delegated
• steps: Array of execution steps
• tool: Tool name (e.g. add_feature)
• action: Manual action description when no tool (e.g. update_project_context)
• args: Tool parameters
• outputs: Expected artifacts
• when/dependsOn/note: Optional conditions and notes

🧩 Structured Output Field Specification (Key Fields)

Both orchestration and atomic tools return structuredContent, common fields:

• summary: One-line summary
• status: Status (pending/success/failed/partial)
• steps: Execution steps (orchestration tools)
• artifacts: Artifact list (path + purpose)
• metadata.plan: Delegated execution plan (only start_*)
• specArtifacts: Specification artifacts (start_feature)
• estimate: Estimation results (start_feature / estimate)

🧠 Requirements Clarification Mode (Requirements Loop)

When requirements are unclear, use requirements_mode=loop in start_feature / start_bugfix / start_ui.
This mode performs 1-2 rounds of structured clarification before entering spec/fix/UI execution.

Example:

{
  "feature_name": "user-auth",
  "description": "User authentication feature",
  "requirements_mode": "loop",
  "loop_max_rounds": 2,
  "loop_question_budget": 5
}

🧩 Template System (Regular Model Friendly)

add_feature supports template profiles, default auto auto-selects: prefers guided when requirements are incomplete (includes detailed filling rules and checklists), selects strict when requirements are complete (more compact structure, suitable for high-capability models or archival scenarios).

Example:

{
  "description": "Add user authentication feature",
  "template_profile": "auto"
}

Applicable Tools:

• start_feature passes template_profile to add_feature
• start_bugfix / start_ui also support template_profile for controlling guidance strength (auto/guided/strict)

Template Profile Strategy:

• guided: Less/incomplete requirements info, regular model priority
• strict: Requirements structured, prefer more compact guidance
• auto: Default recommendation, auto-selects guided/strict

Parent-Child Specifications

For version-level or epic work, start_feature defaults to spec_layout: "auto" and selects parent-child when the requirement spans multiple modules, stages, or capability domains. If child boundaries are not known yet, the delegated plan first returns a decompose-spec step. You can still explicitly pass flat or parent-child; add_feature remains an atomic tool and defaults to flat unless the layout and subspecs are already defined. The MCP server returns templates and pendingFiles; the calling Agent creates the parent spec, spec-manifest.json, and child specs after review. check_spec then validates the complete hierarchy recursively.