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 (defaulthttp://localhost:8000)HOKMAH_MCP_PORT— port to listen on (default8001)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.
Built by
Catalyst AI Research · Haifa, Israel
License
MIT
