Mastermind MCP server
Commit Nov 9, 2026Provides coding agents with local repository context, code search, project knowledge, and evidence-backed task verification workflows.
Also known as xcrft/mastermind
- Stars
- 13
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is Mastermind MCP?
Mastermind provides coding agents with local repository context, code search, project knowledge, and evidence-backed task verification workflows.
Summary generated from the project's README
About Mastermind MCP server
Providing coding agents with local repository context and evidence-backed verification is what Mastermind enables for developers. It allows AI clients like Claude Code and Codex to access indexed code, documentation, and project-specific knowledge to improve task accuracy. By running the init command within a repository, users can connect these clients to receive Git observations and reviewed preferences through prompt hooks.
The system manages a structured workflow that moves from defining criteria to implementation, auditing, and final review. It uses a controller to check task evidence before a job is marked as complete. Developers can use the Lens UI to inspect changes against a Git baseline or use the command line to manage specifications and status. While it supports various languages including Python, Rust, and TypeScript, native hooks and supervised execution require macOS or Linux, whereas Windows users can utilize local indexing.
Setup requires Node.js 24+ and is installed via npm. The tool operates locally, creating a .mastermind directory for working data, which should be kept out of version control. It does not launch a separate model but instead uses the existing client's capabilities to process context and preferences.
What you can do with it
- 1Verify task completion with evidenceAn AI agent can follow a structured workflow to ensure all acceptance criteria and checks are met before finishing a task.
- 2Search local project knowledgeDevelopers can provide agents with deep context by indexing the repository's code and documentation.
- 3Apply personalized coding habitsThe server can deliver specific advisory preferences and habits to the AI client based on the user's role or project.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablexcrft/mastermind is public and reachablegithub.com/xcrft/mastermind ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/xcrft/mastermind ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMastermind gives coding agents local code and documentation search, project knowledge, optional personal preferences, and a controller that checks task evidence before completion.
Quick start
Current-task mining requires Mastermind 3.2.1 or newer. See the source build instructions for local development.
Requires Node.js 24+. The npm manifest lists prebuilt binaries for macOS, Linux, and Windows. Run these commands inside your repository:
npm install -g @xcraftmind/mastermind
mastermind init
The first run detects the active client, or the installed Claude Code and Codex
clients. It creates project guidance, indexes code and documentation, connects
the clients, and enables profile delivery and --mining task. Preferences are
proposed by the current agent and saved locally after complete capture. No
separate model is launched. Use --client none for local indexing only.
Saved choices survive repeated init.
| Command | Result |
|---|---|
mastermind init |
Apply saved project choices from .mastermind/setup.json |
mastermind status --json |
Inspect the index, client configuration, session observations, and miner |
mastermind update |
Update the package in its existing npm scope and refresh installed workflows |
mastermind ui --since main |
Open the read-only Lens UI against your chosen Git baseline |
Restart the selected client and review the generated definitions in /hooks.
Registration, session
observations, and client trust are separate states. Keep .mastermind/ working
data out of version control. See Getting started for
mining choices, Windows support, and other installation paths.
What you can do
| Need | Result |
|---|---|
| Review a change | Changed symbols, callers, boundaries, and candidate tests |
| Find context | Code search, cited Markdown, decisions, and task history |
| Apply working preferences | Reviewed habits selected by project, role, and workflow |
| Delegate a task | Approved scope, observed checks, audit, and semantic review |
| Share evidence | Lens, offline HTML, SARIF, and audit envelopes |
| Import analysis | SCIP, scanner reports, coverage, tests, traces, and facts |
Give an agent useful context
init --client claude|codex|all connects Claude Code, Codex, or both.
Selected clients receive relevant Git observations and reviewed preferences
through prompt hooks and MCP. Git observations refresh locally at init and task
boundaries. macOS and Linux support native hooks.
Other clients use MCP setup.
| Context | Scope |
|---|---|
| Person | Advisory habits and preferences shared across repositories |
| Project | Repository decisions, constraints, and knowledge |
| Code and documentation | Indexed structure and cited source material |
| Role | Duties for this invocation |
| Workflow | Planning, execution, verification, and review |
| Task evidence | Results, blockers, and the reviewed revision |
Profile access is scoped to the selected project and clients. Use
--profile-access off to disable it, or --mining capture to collect without
semantic analysis. Preferences grant no action permissions. Context previews expose revisions
and omissions, not proof of model use. See Architecture
and Persona hooks.
Take a task through review
mastermind new-spec "Add account recovery"
Fill the goal, scope, acceptance criteria, and checks, then follow the Workflow guide:
criteria → implementation → checks → audit → review → complete or feedback
Any client can implement the spec. Recorded native execution and review use Claude Code. Completion requires current evidence and resolved review.
Limits
| Boundary | Meaning |
|---|---|
| Static codegraph | Dynamic dispatch, reflection, generated code, and cross-language calls may be incomplete |
| Personal profile | Reviewed preferences remain advisory |
| Task records | Local evidence does not independently establish correctness |
| Native process policy | Uses client restrictions, not an OS sandbox |
| Task mining | Uses the current agent's allowance for added context and tools. Drafts require review |
| Separate model requests | Background mining, refinement, drafting, execution and review require their own options. See provider contracts |
Language coverage includes Python,
TypeScript/TSX, JavaScript/JSX, Vue SFC, Rust, C#, Go, Java, PHP, and C/C++.
Native hooks, managed mining, and supervised execution require macOS or Linux.
Windows can use local indexing and client setup with --mining off. See
runtime support.
Documentation
| Start | Reference |
|---|---|
| Getting started | CLI and MCP |
| Architecture | Benchmarks |
| Workflow | Changelog |
| All guides | Security policy |
Build and contribute
Source builds require Rust 1.96+, declared in Cargo.toml.
cargo install --path mcp/servers/mmcg --locked
just check
Cargo installs mmcg. npm exposes mastermind and mmcg.
See Contributing, GitHub Issues,
and the security reporting policy.
License
MIT.
Mastermind MCP questions
What does Mastermind provide to coding agents?
It gives agents local code and documentation search, project knowledge, personal preferences, and a controller to check task evidence.
Which programming languages are supported?
Supported languages include Python, TypeScript, JavaScript, Vue, Rust, C#, Go, Java, PHP, and C/C++.
Can I use Mastermind on Windows?
Yes, Windows users can use local indexing and client setup with the --mining off flag.