@getmikk/mcp-server 1.6.0 → 1.8.0

package/README.md

@@ -1,8 +1,17 @@
 # @getmikk/mcp-server
 
-MCP (Model Context Protocol) server for [Mikk](https://github.com/Ansh-dhanani/mikk) — plugs your project's architectural intelligence directly into AI assistants like Claude, Cursor, and any MCP-compatible client.
+> Give your AI assistant real architectural intelligence — not guesses.
 
-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, not guesses.
+[![npm](https://img.shields.io/npm/v/@getmikk/mcp-server)](https://www.npmjs.com/package/@getmikk/mcp-server)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../../LICENSE)
+
+MCP (Model Context Protocol) server for [Mikk](../../README.md) — 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](../../README.md) — the codebase nervous system for AI-assisted development.
 
 ---
 
@@ -61,23 +70,27 @@ mikk-mcp /path/to/project
 
 ---
 
-## Tools (12)
+## Tools (15)
 
 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, constraints that apply, full blast radius |
+| `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) |
 
 ### Staleness warning
@@ -149,13 +162,37 @@ 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, and the top 30 impacted functions.
+Returns `changedNodes`, `impactedNodes`, depth, confidence, `classified` risk breakdown, and the top 30 impacted functions.
 
 ---
 
@@ -163,8 +200,9 @@ Returns `changedNodes`, `impactedNodes`, depth, confidence, and the top 30 impac
 
 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. **Renaming a function** → call `mikk_find_usages` first
-4. **Exploring the project** → `mikk_get_project_overview` → `mikk_get_module_detail`
+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`
 
 ---