MCP Probe Kit

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

知时MCP | mcp-probe-kit Know the Context, Feed the Moment.

Introspection · Context Hydration · Delegated Orchestration

---

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 29 model-visible tools by default (24 base + 5 History Session; disable History with MCP_HISTORY_SESSION=0), 35 when Memory is also configured, and a 39-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.
• History Session (default ON): lossless local chat handoff under docs/history-session/ — bootstrap → checkpoint → search/read, no vector DB required.
• 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](https://mcp-probe-kit.bytezonex.com/pages/apps.html)

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

---

📚 Complete Documentation

👉 [https://mcp-probe-kit.bytezonex.com](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 (+ History), 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 base compact tools, plus 5 History Session tools by default (history_session_bootstrap|checkpoint|validate|search|read) for a 29-tool model surface. Set MCP_HISTORY_SESSION=0|false|off to hide History. When the full Memory stack is configured, six Memory tools are added dynamically, bringing the model-visible surface to 35 (or 30 if History is off):

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

📜 History Session (default ON) — lossless project handoff

Chat hosts forget. History Session keeps a lossless, project-local archive so the next Agent turn (or a new conversation) can resume with real user wording, decisions, and open items — without stuffing the whole chat into the prompt.

Why it matters

• Host context windows and “new chat” resets drop prior findings; History persists them as Markdown under docs/history-session/.
• Default ON and no Qdrant / embedding stack — works out of the box alongside the 24 base compact tools (29 model-visible tools total).
• Complements, does not replace, the other layers:

How Agents use it

1. Start of a conversation — history_session_bootstrap with initial_user_input= . On hosts without a platform session, omit session_key once; the server mints hs_ and opens a new archive (it does not share project-active). Echo that handle on later calls. Do not invent keys.
2. Before each final reply — history_session_checkpoint with the bootstrap session_key + expected_path, plus this turn’s raw_user_input / user_intent. Fill the Skill minimum checklist (findings, decisions, files_changed, tests, runtime_state, next_actions) — no empty-array padding.
3. Need an older fact — history_session_search → history_session_read (follow next_cursor). Prefer bounded bootstrap state first; do not load full history by default.
4. Numbering / index damage — history_session_validate (repair=true when needed).

Operational details

• Soft-rotate when an archive exceeds MCP_HISTORY_MAX_LINES / MCP_HISTORY_MAX_BYTES (defaults 800 / 131072); checkpoint returns the new expected_path. Rotated archives carry forward the latest initial_user_input.
• Redacts common secrets in archived text; checkpoints are idempotent by content fingerprint.
• Disable with MCP_HISTORY_SESSION=0|false|off (hides the five tools).
• Do not commit docs/history-session/ — add it to .gitignore (local handoff only; not part of the npm package story).

Skill and AGENTS.md spell out the read/write timing rules; the All Tools catalog lists one-line call prompts for each history_session_* tool.

🔁 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