Hokmah MCP Server

AI Agent with Architectural Memory — MCP Server

Gives any AI coding agent persistent understanding of codebases via TransitionGraph, IdeaGraph, and WorldModel. Analyze impact, generate tests, write code — all from the graph.

Quick Start (30 seconds)

Add to your editor's MCP config (Cursor, Claude Code, VS Code, Windsurf, Cline, JetBrains):

json

{
  "mcpServers": {
    "hokmah": {
      "type": "streamable-http",
      "url": "https://hokmah.dev/mcp"
    }
  }
}

Then ask your agent: "analyze the impact of refactoring the auth module in github.com/owner/repo"

Available Tools

Tool	Tier	Description
`hokmah_analyze`	FREE	Impact analysis, risk score, affected files, architectural invariants
`hokmah_connect_project`	FREE	Connect a GitHub repo, build the architectural graph
`hokmah_connect_mcp`	FREE	Connect an external MCP server for orchestration
`hokmah_generate_tests`	PRO	Test generation from the graph (40x fewer tokens)
`hokmah_generate_code`	PRO	Code generation with architectural memory

How It Works

Hokmah builds a persistent architectural graph from your codebase:

TransitionGraph — Markov model of code changes (which files change together)
IdeaGraph — 16 relation types between concepts
WorldModel — File tree, dependencies, symbols

When you ask "what's the impact of changing X?", Hokmah traverses the graph instead of sending your entire codebase to an LLM. That's why analyze is free (zero LLM tokens) and generate uses 40x fewer tokens.

Pricing

Free — hokmah_analyze + hokmah_connect_project + hokmah_connect_mcp (unlimited)
Pro — hokmah_generate_tests + hokmah_generate_code (BYOK — bring your own LLM key)

Get a Pro key at hokmah.dev.

Editor Setup

Cursor — Settings → MCP → Add server → paste config
Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code — claude mcp add hokmah --transport streamable-http --url https://hokmah.dev/mcp
VS Code (Copilot) — .vscode/mcp.json in project root
Windsurf — ~/.windsurf/mcp.json
Cline — Settings → MCP Servers → Add
JetBrains — Settings → Tools → AI Assistant → MCP Servers

Self-Hosting

The hosted server at https://hokmah.dev/mcp is the recommended way to use Hokmah. To run the server yourself against your own Hokmah backend:

bash

pip install -r requirements.txt
cp pro_keys.example.json pro_keys.json  # edit with your real PRO keys
HOKMAH_API_BASE=http://localhost:8000 python mcp_server.py

Environment variables:

HOKMAH_API_BASE — upstream Hokmah API (default http://localhost:8000)
HOKMAH_MCP_PORT — port to listen on (default 8001)
HOKMAH_PRO_KEYS — path to the PRO keys JSON file (default /home/vpm/mcp-server/pro_keys.json)

A reference systemd unit is provided in hokmah-mcp.service.