Summary: M7 MCP is a methodology-enforcing MCP server that guides AI coding agents through structured seven-phase cycles with memory, analysis, validation, and project-knowledge tools.
Enforce the seven-phase cycle from intake through implementation, with gates, artifacts, reflection checks, rule re-injection, and persistent cycle state.
Analyze and route tasks, create/reuse sessions, detect chaos or scope drift, and choose short-path versus full-cycle handling.
Manage tiered memory (L0-L4), fog-of-war discovery, confidence/invalidation, promotion, consolidation, search, and cleanup.
Track sessions, compliance, health, completion, and scope budgets, with enforcement and emergency overrides.
Initialize projects and generate or update project indexes, schemas, contracts, and knowledge-base documents.
Check technology stacks and code patterns, warn about known footguns, and validate implementations against safety and best-practice rules.
Run baseline audits, dependency checks, visual validation, metrics tracking, and code-impact analysis.
Analyze knowledge graphs and architecture, detect cycles/orphans/antipatterns, generate diagrams, and suggest refactoring.
Coordinate Hive multi-agent analyses and browse saved Hive reports.
Support cross-session learning, style learning/enforcement, error-pattern capture, and task dependency graphs/transfers.
Provide console monitoring, telemetry consent/stats, mesh multi-instance coordination, and DevOps registry/history.
Offer warmup, doctor diagnostics, DCCE dual-channel content generation/validation, safety scans, and litany/repentance methodology tools.
Used by the Hive tool to run OpenAI model instances on a question and merge their answers. Requires an OPENAI_API_KEY, which the server checks at startup.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@M7 MCP analyze adding OAuth login and run it through the full M7 cycle"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Current release: v3.22.2 — clone main or download the release archive. There is no npm package; build from source (npm run build).
An MCP server that makes an AI coding agent work through a fixed seven-phase cycle instead of jumping straight to code. It was built for Cursor, but it speaks plain MCP over stdio and should work with any client that supports tools.
This repository is a snapshot, not the live tree. I developed M7 between June 2025 and mid-2026 as a private tool used by me and my team. The version published here is the state of the repo as of July 2026 with the parts tied to that closed distribution (self-update client, license check, private-access gate) and one unfinished research module removed. Development continues privately; I may or may not sync more of it later. See CHANGELOG.md for what changed when, and docs/WHY_OPEN_SOURCE.md for why this is published as open source rather than pursued as a patent or a company.
The core idea is simple: before the agent touches code it has to go through
discovery, architecture, solution, impact analysis and an implementation
simulation, write an artifact for each, and pass a reflection gate between
phases. The server does not trust the model to "remember" the rules: it
issues a gate ID with every phase instruction, rejects reflections that do not
quote it, re-injects a compact rule summary after N calls to mcp_m7_cycle within the
same phase (the MCP server only observes its own tools, not the client's other
actions), and keeps the cycle state on disk so a new chat can pick up where the
old one stopped.
Around that cycle there is a set of supporting tools:
Memory with tiers (L1/L2/L3), confidence decay, promotion and a "fog of war" that tracks what is known, assumed, stale or unknown about the project. Optional ChromaDB backend for semantic search; falls back to local JSON.
Task analysis and routing (mcp_m7_analyze_task): classifies a request,
creates a session, flags scope drift, decides between a short path and the
full cycle.
Hive: run several model instances (OpenAI / Anthropic) on a question and merge the answers. Needs API keys.
TSI (tech safety intelligence): YAML pattern packs (security, performance, architecture, testing, deployment) used to warn about known footguns before implementation.
Task graph, task transfer between chats, architecture advisor, knowledge
graph, error database, style guardian, DCCE text validator, mesh for
multi-machine sessions, and a few more. The full list is in
docs/TOOLS_REGISTRY.md; 37 tools are registered
by src/index.ts.
Documentation is split by reader. For the agent: M7-GUIDE.md
(operational guide) and
Methodology/CURSOR_METHODOLOGY_RULES.md
(rules for .cursorrules). For people: docs/M7_WHY_FULL_CYCLE.md
(why a fixed cycle), docs/methodology/M7_IDEAL_PRINCIPLES.md
(principles and where they are implemented) and
Methodology/IDEAL_METHODOLOGY.md (process
specification). The index is Methodology/METHODOLOGY_INDEX.md.
Related MCP server: agendum
For context, since harness-engineering frameworks became a popular topic in 2026:
June–July 2025: first prototype (0.1.0 → 1.0.0), 11 tools, basic memory, 7-phase cycle as a prompt-level protocol.
August 2025: 2.0.0 — Hive multi-agent, tiered memory, scope management.
Late 2025: TSI, telemetry (opt-in), context visualizer.
February–March 2026: cycle orchestrator v2 with reflection gates, carry-forward context, template-driven artifacts.
July 2026: epistemic layer (fog of war boundaries, grounding gate, adversarial review gate, control-channel nonce, rule re-injection).
October 2026: the "Deep Scan M7" review by @DiadkoShmek, then public community-fix batches on KNOWN_ISSUES.md — v3.18.1 (batch 1), v3.19.0 (Stage 1 remainder + Stage 2 cycles), v3.20.0–v3.22.2 (Stage 2–3, acceptance suites; every item on the list is fixed); see docs/COMMUNITY_SPRINT.md.
Node 22 or newer
OPENAI_API_KEY and ANTHROPIC_API_KEY. The server checks both at startup
and refuses to run without them; this is a leftover of the Hive-first design
and is on the list of things to relax. Placeholder values are enough if you
do not use Hive.
Optional: ChromaDB at CHROMA_URL (default http://localhost:8000) for
vector memory.
git clone https://github.com/DukeDeSouth/m7-mcp-oss.git m7-mcp
cd m7-mcp
npm install
npm run buildThen add the server to your MCP client. For Cursor, ~/.cursor/mcp.json:
{
"mcpServers": {
"m7": {
"command": "node",
"args": ["/absolute/path/to/m7-mcp/dist/index.js"],
"cwd": "/absolute/path/to/m7-mcp",
"env": {
"OPENAI_API_KEY": "sk-...",
"ANTHROPIC_API_KEY": "sk-ant-...",
"M7_PROJECT_PATH": "/absolute/path/to/your/project"
}
}
}
}install.sh does the same interactively. M7_PROJECT_PATH is optional: the
server tries MCP roots and a few environment hints first, but setting it
explicitly avoids surprises when several workspaces are open.
Run mcp_m7_init_project once inside a project. It creates the memory bank,
project knowledge files and a .cursorrules with the methodology summary.
From then on, start tasks with
mcp_m7_analyze_task and follow the instructions the server returns.
Feature flags and cycle thresholds are in config/m7-config.yaml. Defaults are
in src/core/config/featureFlags.ts. Useful environment variables:
Variable | Purpose |
| target project directory |
| verbose logs on stderr |
| enable telemetry upload to a collector you run; unset means nothing leaves the machine |
| override how many |
| ChromaDB base URL |
Telemetry is off by default and, even when you opt in with
mcp_m7_telemetry, nothing is sent unless M7_TELEMETRY_ENDPOINT is set.
Everything lives in the project directory: .m7/, m7-cycles/ and
CYCLE_REGISTRY.md.
Cycle state: .m7/cycles/<task-id>.json plus a reflection log. When a
new cycle starts, finished or aborted cycles untouched for 7 days are moved
to .m7/cycles/archive/. Active cycles are never moved, and nothing in the
archive is deleted.
Cycle artifacts: m7-cycles/<slug>-<id suffix>/, one folder per cycle,
plus one row per cycle in CYCLE_REGISTRY.md. The server never deletes them. A
resubmitted phase is appended to its file, not overwritten.
Memory: L0 (100 records) and L1 (500) are RAM only; the oldest records
are dropped when a level is full, and both levels are empty after a
restart. L2 and L4 go to .m7/memory/longterm.json, L3 to
conceptual.json, the fog of war to fog_of_war.json, and deletions to
.m7/memory-tombstones.json. These have no size limit and are kept until you
delete records with mcp_m7_memory (invalidated records stay, marked as
such). Writes are batched for
up to a second and flushed on shutdown.
Task sessions (.m7/orchestrator-sessions.json) are kept until you
delete the file. Cross-session learning (.m7/cross-session/) is
pruned only when you call mcp_m7_cross_session with action: "cleanup".
By default that drops insights unused for 90 days or below confidence
0.2.
Telemetry events (.m7/telemetry/): the file is rotated at 10 MB and
rotated files are deleted after 7 days.
State files written atomically keep up to three previous versions next to
them (.bak.1 … .bak.3). These are used for recovery when the main file
is unreadable.
Other tools keep their own files under .m7/ (style profile, knowledge graph,
TSI, mesh). None of it leaves the machine unless you configure an endpoint for
it.
npm run build # tsc → dist/
npm test # scripts/run-tests.sh: each tests/*.test.mjs with a timeout
M7_DEBUG=true node dist/index.js # run the server by handTests import from dist/, so build first. Tests that write state use their own
temporary project, and npm test fails if a run leaves files in the repository.
Both API keys are required at startup even if you never call Hive.
The grounding gate checks that the files and memory records a step cites exist. It does not check that they support the step's claim.
src/tsi loads its YAML patterns from src/tsi/patterns even when running
from dist/, so run it from a clone, not from a copied dist/.
Some modules keep timers alive after the work is done; the test runner uses
--test-force-exit for that reason.
Comments and some docs are a mix of English and Russian.
Project-path resolution scans ~/.cursor/projects as one of its fallbacks.
If you are not using Cursor, set M7_PROJECT_PATH.
See CONTRIBUTING.md. Issues and PRs are welcome; I cannot promise fast turnaround. If you want something concrete to work on, KNOWN_ISSUES.md lists confirmed defects with code references and a suggested order. The first response sprint (Stage 1 batch 1) is documented in docs/COMMUNITY_SPRINT.md.
@DiadkoShmek wrote "Deep Scan M7" (October 28, 2026), a source-level review of the 3.18.0 snapshot. Most of KNOWN_ISSUES.md and the fixes in v3.19.0–v3.22.2 come from it. @conradipui-glitch found and fixed the Windows write and project-path bugs (#9).
Apache License 2.0. See LICENSE.
Analyze task complexity and route appropriately with chaos detection, baseline audit and orchestration
Inputs: task_description (required), context, reuse_session, create_session, +1 more.
Architectural Advisor - analyze architecture, detect antipatterns, generate C4 diagrams, suggest refactoring.
Actions:
analyze: Full analysis with score (A-F grade)
detect_antipatterns: Find architecture problems
suggest_refactoring: Get actionable improvement steps
generate_c4: Generate C4 architecture diagrams
score: Quick score summary
critical_issues: Only critical problems
top_suggestions: Best improvement opportunities
Inputs: action (required), limit, c4_level, project_path, +3 more.
Check error journal to avoid repeating past mistakes
Inputs: error_type.
Check technology stack for safety patterns and potential issues
Inputs: task (required), technology (required), timeline, constraints, +4 more.
Smart console monitoring and error capture
Inputs: action (required), limit, filter, minutes.
API contract registry management to prevent duplicate methods
Inputs: action (required), name, type, filter, +2 more.
[DEPRECATED v5.0] Use mcp_m7_cycle instead. Create M7 file structure for a task
Inputs: route (required), task_id (required), status, version, +1 more.
M7 v3.0 Cross-Session Learning - Learn from session patterns across time.
Check cross-session learning system status.
Start tracking a new session.
session_id: Session ID to track (required)
Record an action in current session.
action_data: { type, tool?, input, output, file?, success, userFeedback? }
Get full project learning context for AI prompts.
Search relevant knowledge.
query: Search query (required)
limit: Max results (default: 5)
Validate an insight (user feedback).
insight_id: Insight ID (required)
valid: true/false (required)
Record CI/CD result for insight validation.
ci_result: { type, success, details?, affectedInsights? }
Get learning statistics.
Cleanup old/low-confidence data.
cleanup_options: { olderThanDays?, belowConfidence? }
Format context for injection into AI prompt.
query: Optional query for relevant knowledge
Inputs: action (required), limit, query, valid, +5 more.
Start or continue M7 cycle with explicit phase instructions. Use for structured task development through all 7 phases: intake → discovery → architecture → solution → impact → simulation → implementation.
Inputs: summary, task_id, artifact_content, task_description.
DCCE (Dual-Channel Content Envelope) — generate, validate, render and lint dual-channel content. Two channels: Human View (3-5 sentences for humans) and AI View (structured JSON for machines). AI stays AI, no mimicry.
Inputs: action (required), ai, text, actor, +9 more.
DevOps registry: управление средами, валидация команд, история деплоев
Inputs: action (required), limit, command, version, +3 more.
M7 Doctor - диагностика и авто-исправление проблем с .m7/ директорией
Inputs: action, verbose, project_path.
M7 v3.0 Error Pattern Database - Track AI mistakes and provide preventive warnings.
Record an AI mistake.
category: Error category (required): syntax, type, import, api, logic, style, security, performance, compatibility, other
title: Error title (required)
ai_mistake: What AI generated wrong (required)
correct_solution: What it should have been (required)
description: Detailed description
explanation: Why it was wrong
severity: critical, high, medium, low
project_id: Project identifier
tags: Array of tags
Check code for potential errors.
code: Code to check (required)
file: File path for context
Search the error database.
query: Search text
category: Filter by category
severity: Filter by severity
project_id: Filter by project
limit: Max results (default: 20)
Get error statistics.
project_id: Filter by project (optional)
List or manage error patterns.
pattern_action: list, enable, or disable
pattern_id: Pattern ID for enable/disable
Record a correction for an error.
error_id: Error ID to correct (required)
original_code: Original wrong code (required)
corrected_code: Corrected code (required)
Report a false positive warning.
pattern_id: Pattern ID that gave false positive (required)
Clear all error data.
Inputs: action (required), code, file, tags, +17 more.
Get recommended patterns and antipatterns for a specific technology
Inputs: technology (required), tags, type, limit, +6 more.
Orchestrate multiagent collaboration for complex tasks using M7 Hive system.
v3.8.0 Features:
DYNAMIC MODE (default): AI creates optimal expert team for each task
PLANNED MODE (new): CNP auction-based coordination with task decomposition
MODEL SELECTION: Best model chosen per agent based on LiveBench benchmarks
SELF-LEARNING: System improves over time based on results
GATEKEEPERS: Style, Architecture, Security validation
Use mode="dynamic" for quick expert analysis (default). Use mode="planned" for complex tasks requiring decomposition and validation. Use mode="fixed" for legacy behavior with predefined agents.
Inputs: task (required), mode, agents, priority, +3 more.
Browse and load past Hive analysis reports.
Use "list" to see all saved reports with dates, topics, and sizes. Use "load" with a filename to bring a full report into the conversation context.
Reports are saved automatically when running mcp_m7_hive_coordinator. Use this tool to reference past analyses in follow-up discussions.
Inputs: action (required), limit, query, filename.
Code Impact Analyzer - анализ реальных изменений кода
Inputs: action (required), after, depth, files, +2 more.
Initialize complete M7 ecosystem for empty projects - creates Memory Bank, .cursorrules, project structure
Inputs: force, domain, description, project_name, +2 more.
Project Knowledge Graph - analyze code dependencies, detect cycles, find orphans, generate diagrams.
Build graph from project directory.
rootPath: Root directory to scan (required)
include: File patterns to include (default: **/*.ts, **/*.tsx, **/*.js)
exclude: File patterns to exclude (default: node_modules, dist)
Get current graph status and summary.
Get detailed graph metrics (nodes, edges, coupling, cohesion, health grade).
Query nodes with filters.
nodeType: Filter by type
name: Filter by name (regex)
filePath: Filter by path
limit: Max results
Search nodes by name.
name: Name to search (required)
Get dependencies of a node.
nodeId: Node ID (required)
Get dependents of a node (what depends on it).
nodeId: Node ID (required)
Analyze impact of changing a node or file.
nodeId: Node ID to analyze
filePath: File path to analyze
Detect circular dependencies.
maxCycles: Max cycles to return (default: 100)
includeTypeOnly: Include type-only cycles
Find orphan code (unused exports).
Generate Mermaid diagram.
diagramType: dependency, class, component, module, impact
nodeId: Root node for impact diagram
maxNodes: Max nodes to show
direction: TB, BT, LR, RL
Find shortest path between two nodes.
nodeId: Source node (required)
targetId: Target node (required)
Get most critical paths (highest impact nodes).
limit: Number of nodes to return
Export graph to JSON.
Import graph from JSON.
data: JSON string (required)
Clear the graph.
Inputs: action (required), data, name, limit, +13 more.
Manage project knowledge base - centralized documentation system with versioning and auto-sync
Inputs: action (required), force, version, to_version, +3 more.
Litany of Ignition — Recite sacred texts from the Codex Martianus before beginning work. The Inner Litany, the Sevenfold Rite, and random wisdom from the Archmagos-Forerunner.
Inputs: action (required), phase, section.
Unified M7 Memory System - 5-level cognitive hierarchy with FogOfWar
L0 (surface): Ephemeral, seconds-minutes
L1 (working): Task context, hours-days
L2 (longterm/project): Project patterns, weeks-months
L3 (conceptual): Validated patterns, months-years
L4 (global): Universal knowledge, permanent
search: Cascade search L0→L4 with early stop
search_level: Search specific level
store: Store with auto-level (default L0)
store_at: Store at specific level
get: Get record by ID
delete: Delete record (from memory AND disk)
delete_bulk: Delete multiple records by IDs array
invalidate_bulk: Invalidate multiple records by IDs array
stats: Memory statistics (deduplicated)
discover_technical: Add FogOfWar discovery
query_fog_of_war: Query low confidence areas
promote: Manual promotion to higher level
consolidate: Submit validated L2+ summary for needs_consolidation records
invalidate: Mark record as invalidated
reload: Reload memory from disk (resync after manual edits)
Inputs: action (required), id, ids, path, +22 more.
M7 Mesh — Multi-instance communication and coordination.
Connects M7 instances across machines via relay server, or locally via SQLite.
sync: Full sync — push state, pull peers/changes/messages
push: Push shared doc to relay (path, content)
pull: Pull shared doc from relay (path)
notify: Notify peers about file change (path, summary)
changes: View file change feed from peers
ask: Ask a question to specific peer or all (to, question)
reply: Reply to a message (message_id, answer)
inbox: View unread messages
broadcast: Send note to all peers (message)
log_task: Register M7 task in shared index (task_id, title, status, summary)
tasks: View shared task index
push-file: Read local file and push to relay (path) — auto-notifies peer
pull-file: Pull file from relay and save to local disk (path)
list-files: List all shared files on relay
init: Initialize mesh (auto-detects remote if configured)
status: Show mesh health
announce: Publish context
peers: List peers
request_context: Query peer context
Inputs: action (required), to, path, limit, +25 more.
Automatically generate and manage PROJECT_INDEX.md file with comprehensive project information for AI assistants
Inputs: action (required), force, sections, template, +7 more.
Litany of Unbinding — AI confesses when it deviated from M7 methodology. Record freestyle mistakes, view the Wall of Shame, track heresy statistics.
Inputs: action (required), heresy, project, how_m7_helped, +2 more.
Safety pipeline: detect jailbreak patterns, verify intent, check outputs. Actions: scan_input | scan_output | full_check | verify_intent | catalog_stats
Inputs: action (required), text, input, output.
Manage project schema (database, API, architecture) - prevents duplicate databases and maintains project consistency
Inputs: action (required), format, changes, component.
Manage task scope and prevent scope creep
Inputs: action (required), budget, reason, sessionId.
Unified M7 session management - status, compliance, completion, enforcement
Inputs: action (required), force, notes, evidence, +3 more.
M7 v3.0 Style Guardian - Learn and enforce code style patterns.
Analyze a project/directory to learn style patterns.
path: Directory path to analyze (required)
Validate code against learned style profile.
code: Code to validate (required)
file: File path for context
Quick check for errors only (blocking issues).
code: Code to check (required)
file: File path
Auto-fix code where possible.
code: Code to fix (required)
file: File path
Record a user correction for learning.
original: Original (wrong) code (required)
corrected: Corrected code (required)
file: Source file
context: Additional context
Get current style profile.
Get learning statistics.
Export all corrections as JSON.
Import corrections from JSON.
corrections: JSON string of corrections (required)
Clear all learned data.
Inputs: action (required), code, file, path, +5 more.
View and explore the task dependency graph
Inputs: action (required), depth, limit, filter, +1 more.
Transfer tasks when scope grows beyond original estimate
Inputs: action (required), reason, task_id, new_title, +1 more.
M7 Code Telemetry - manage consent, view statistics, help improve AI models
Inputs: action (required), data_types.
Unified M7 validation operations - audit, visual testing, dependencies, metrics
Inputs: action (required), url, code, phase, +13 more.
Validate code implementation against safety patterns and best practices
Inputs: code (required), technology (required), strict_mode, custom_rules, +5 more.
M7 Context Visualizer - interactive graph visualization of code dependencies.
Actions:
start: Start the visualizer server (opens web UI)
stop: Stop the visualizer server
status: Check if server is running
set_context: Update current file/task context
get_graph: Get graph data as JSON
focus: Focus on a specific node
open: Get URL to open visualizer
The visualizer shows:
Code dependency graph with live updates
Current editing context ("You are here")
Impact analysis (what changes affect)
Navigation history
Health metrics
Use 'start' to launch, then open the URL in browser.
Inputs: action (required), file, task, node_id.
M7 Warmup System — прогрев контекста проекта для нового чата. Загружает полную информацию о проекте и выдаёт отчёт для проверки.
Inputs: action (required), force, scope, success, +2 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 37 tools
Several tools have overlapping purposes: mcp_m7_validate, mcp_m7_validate_implementation, mcp_m7_safety_verify, mcp_m7_check_tech_stack, mcp_m7_style_guardian.validate/check, and mcp_m7_error_database.check all perform some form of code checking or validation. mcp_m7_impact overlaps with mcp_m7_knowledge_graph's impact action, and multiple knowledge/memory tools (memory, knowledge_hub, cross_session, knowledge_graph) are hard to distinguish at a glance.
All tool names use snake_case with a consistent mcp_m7_ prefix, which is readable and predictable. However, the naming mixes verb-style names (analyze_task, check_errors, create_structure) with noun-style names (schema, mesh, memory, session, console, contracts, telemetry), so the pattern is not fully consistent.
With 37 tools, the surface is heavy for a methodology/workflow server, and many tools are mega-tools exposing 8-20 internal actions. The count feels excessive and increases selection burden rather than being a tightly scoped set.
The tool set covers a broad M7 lifecycle: project initialization, cycle management, task analysis, scoping, session tracking, memory, knowledge graph, contracts, validation, safety, style, telemetry, DevOps, and visualization. Minor gaps exist around clear CRUD-style operations for some registries, but core workflows appear covered.
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
The project brain for AI coding agents — memory, decisions, sprints, knowledge base via MCP.
Project memory, documentation and controlled secret access for AI coding agents.
Project memory for coding agents: requirements, decisions, code graph and delivery telemetry.
