mindforge

mindforge-mcp-server

Read the MindForge engine — knowledge graph, project health, and audit log — from Claude Code or any MCP host, over stdio.

A self-contained Model Context Protocol (MCP) server that exposes the MindForge engine to AI agents: query the SQLite-backed knowledge graph, find related memory, check project health, and read the tamper-evident audit log — plus one guarded write to persist new knowledge. Zero runtime dependencies (the server and its deps are bundled into a single file), so it runs on a clean install, offline, and on first session.

Install

claude mcp add mindforge -- npx -y mindforge-mcp-server

Or add it manually to your MCP host config (Claude Desktop, Cursor, VS Code):

{
  "mcpServers": {
    "mindforge": {
      "command": "npx",
      "args": ["-y", "mindforge-mcp-server"],
      "env": { "CLAUDE_PROJECT_DIR": "${workspaceFolder}" }
    }
  }
}

The server scopes every operation to CLAUDE_PROJECT_DIR (the project containing .mindforge/ and .planning/). If unset, it falls back to the current working directory. Every tool degrades gracefully with an actionable message when MindForge is not initialized in the project — it never throws.

Tools

Tool	Access	Description
mindforge_health	read-only	Run a MindForge health check on the current project (config, state, knowledge graph, audit chain).
mindforge_status	read-only	Read current project status: whether MindForge is initialized, active phase, and handoff state.
mindforge_memory_query	read-only	Search the knowledge graph (architectural decisions, patterns, preferences) by topic, tags, and type.
mindforge_memory_stats	read-only	Report knowledge-graph statistics: total/active entries, types, and tag distribution.
mindforge_memory_find_related	read-only	Given free text, find related knowledge entries via hybrid (FTS5 + graph-traversal) retrieval.
mindforge_audit_log	read-only	Read entries from the tamper-evident audit log (.planning/AUDIT.jsonl), optionally filtered by event.
mindforge_memory_remember	write (guarded)	Persist a new knowledge entry (decision, pattern, or preference) into the graph.
mindforge_browse	write (guarded, open-world)	Drive the MindForge browser daemon: status/navigate/click/type/screenshot/assert. Requires the daemon to already be running (/mindforge:browse --start); never spawns it, and never exposes JS eval or cookie import.

All tools are annotated with readOnlyHint / destructiveHint so MCP hosts can enforce the right trust boundary; only mindforge_memory_remember writes, and it is append-only.

Transport & security

• Transport: stdio JSON-RPC (single embedded client).
• Scope: read/append only within CLAUDE_PROJECT_DIR, plus a loopback-only proxy to the MindForge browser daemon (mindforge_browse) — no shell execution. The MCP server process itself only ever talks to 127.0.0.1; the daemon (a separate, pre-existing process this server never spawns) performs the actual browser network egress when a page navigates.
• Self-contained: the SDK and Zod are bundled into dist/index.js; no node_modules are needed at runtime.

Part of MindForge

This server ships standalone (npm + MCP registries) and bundled inside the MindForge Claude Code plugin. For the full framework — slash commands, subagents, governance, and cost-aware model routing — see the main repository.

License

MIT © MindForge Team