@getmikk/mcp-server

Give your AI assistant real architectural intelligence — not guesses.

MCP (Model Context Protocol) server for Mikk — connects your project's full architectural graph directly to AI assistants like Claude Desktop, Cursor, and any MCP-compatible client.

Once connected, your AI assistant can answer questions like "what breaks if I change this file?", "who calls parseToken?", and "what are the architectural constraints for this project?" — all grounded in the actual call graph, real export surfaces, and real constraint definitions. Not hallucinated. Not guessed.

Every tool reads from mikk.lock.json — no re-parsing, millisecond response times.

Part of Mikk — the codebase nervous system for AI-assisted development.

Requirements

• Mikk installed and initialized in your project (mikk.json + mikk.lock.json present)
• Node.js 18+ or Bun 1.x

Installation

npm install -g @getmikk/mcp-server
# or
bunx @getmikk/mcp-server /path/to/your/project

Connecting to an MCP client

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mikk": {
      "command": "npx",
      "args": ["-y", "@getmikk/mcp-server", "/absolute/path/to/your/project"]
    }
  }
}

Cursor / VS Code (via settings.json)

{
  "mcp.servers": {
    "mikk": {
      "command": "npx",
      "args": ["-y", "@getmikk/mcp-server", "/absolute/path/to/your/project"]
    }
  }
}

Direct invocation

mikk-mcp /path/to/project

Tools (22)

All tools read from the lock file (mikk.lock.json) — fast, no re-parsing.

| Tool | Purpose | |---|---| | mikk_get_project_overview | Modules, function counts, tech stack, constraints | | mikk_get_session_context | One-shot AI session start — get project overview, recent changes, hot modules, and constraint status instantly | | mikk_get_changes | What files changed since the last codebase analysis | | mikk_query_context | Ask an architecture question — returns graph-traced context with call chains | | mikk_impact_analysis | Blast radius of changing a specific file | | mikk_before_edit | Call before editing any file — exported functions at risk, actual boundary constraint violations, full blast radius | | mikk_find_usages | Every function that calls a specific function — essential before renaming | | mikk_list_modules | All declared modules with file/function counts | | mikk_get_module_detail | Functions, files, exported API, and internal call graph for a module | | mikk_get_function_detail | Params, return type, call graph, source body, error handling for a function | | mikk_search_functions | Substring search across all function names | | mikk_semantic_search | Natural-language semantic search using local vector embeddings (Xenova/all-MiniLM-L6-v2). Query: "validate a JWT token" returns functions ranked by semantic similarity (e.g. verifyToken, validateJwt). Requires optional @xenova/transformers package. | | mikk_get_constraints | All architectural constraints and design decisions | | mikk_get_file | Read raw source of any project file (with path traversal guard) | | mikk_read_file | Read raw source, scoped only to specific functions to save token context | | mikk_get_routes | Detected HTTP routes (Express / Koa / Hono style) | | mikk_rename | Coordinated multi-file rename plan (definition + call sites + imports) | | mikk_git_diff_impact | Map git diff hunks to affected symbols (added/modified/deleted) | | mikk_manage_adr | CRUD for Architectural Decision Records (ADRs) stored in mikk.json | | mikk_dead_code | Detect dead code (functions with zero callers after exemptions) | | mikk_token_stats | Session token savings and efficiency estimates | | mikk_test_tool | Simple test tool for verifying MCP connectivity |

Staleness warning

If mikk.lock.json is in a drifted or conflict state (i.e., out of sync with the source), every impact-sensitive tool will include a "warning" field in its response:

{
  "warning": "⚠️ Lock file is drifted. Run `mikk analyze` for accurate results."
}

Run mikk analyze in your project to refresh the lock.

Resources (3)

| URI | Content | |---|---| | mikk://contract | The full mikk.json contract as JSON | | mikk://lock | The full mikk.lock.json as JSON | | mikk://context | The claude.md AI context document (if present) |

Tool reference

mikk_before_edit

The most important tool. Call it before editing any file.

files: string[]   # relative paths, e.g. ["src/auth/verify.ts"]

Returns for each file:

• Functions defined in the file
• Exported functions at risk (with their callers)
• Blast radius (how many nodes depend on this file)
• All project-level architectural constraints

mikk_query_context

Ask an architecture question and get back a formatted context block ready to feed into your prompt.

question:     string            # e.g. "How does token refresh work?"
maxHops:      number (default 4)
tokenBudget:  number (default 6000)
focusFile:    string (optional) # anchor traversal from a specific file
focusModule:  string (optional) # anchor traversal from a specific module
provider:     'generic' | 'claude' | 'compact'  (default 'generic')

Returns isError: true with a helpful message if no context was found (e.g. file doesn't exist in the lock).

mikk_find_usages

Find everything that calls a function — complete with file, module, and line number.

name: string   # function name (e.g. "parseToken")

mikk_semantic_search

Find functions by natural-language meaning, not just name matching. Uses local vector embeddings (Xenova/all-MiniLM-L6-v2) to rank functions by semantic similarity.

query:  string   # natural-language description (e.g. "validate JWT token", "send email notification")
topK:   number   # max results to return (default 10)

Example queries:

• "validate JWT token" → ranks verifyToken, validateJwt, checkToken highest
• "send an email notification" → ranks sendWelcomeEmail, notifyUser, emailAlert highest
• "database persistence" → ranks saveUser, storeRecord, commitTransaction highest

Advantages over mikk_search_functions:

• Keyword search: exact substring match (very fast, narrow results)
• Semantic search: meaning match (slower, broader understanding, finds related functions)

Requirements: @xenova/transformers must be installed in your project (npm install @xenova/transformers). The first query will download the model (~22 MB) to ~/.cache/huggingface/ and cache it locally.

Availability check: If @xenova/transformers is not installed, the tool returns a helpful error message with installation instructions.

mikk_impact_analysis

file: string   # relative path to the file being changed

Returns changedNodes, impactedNodes, depth, confidence, classified risk breakdown, and the top 30 impacted functions.

Recommended AI assistant workflow

1. Before editing → call mikk_before_edit with the files you plan to touch
2. Understanding a flow → call mikk_query_context with your question
3. Searching by meaning → call mikk_semantic_search for natural-language queries
4. Renaming a function → call mikk_find_usages first
5. Exploring the project → mikk_get_project_overview → mikk_get_module_detail

License

Apache-2.0