# RepoMind-MCP

[![npm version](https://img.shields.io/npm/v/repomind-mcp.svg)](https://www.npmjs.com/package/repomind-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A local [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI coding assistants a map of your codebase — file structure, import graph, and "what breaks if I change this file" — without dumping the whole repo into the model's context.

It runs entirely on your machine over stdio. No network calls, no uploading code anywhere.

## Quick Start

Add this to your MCP client config (e.g. Claude Desktop's `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "repomind-mcp": {
      "command": "npx",
      "args": ["-y", "repomind-mcp"]
    }
  }
}
```

Restart your client. The assistant can now call the tools below whenever it needs to understand your project's layout instead of guessing.

## What it actually does

Ask your assistant something like *"what would break if I change `src/auth.ts`?"* or *"give me an architecture diagram of this project"* — it reaches for one of these tools instead of grepping blindly:

| Tool | Answers the question... | Key argument |
|---|---|---|
| `repomind_scan_workspace` | "What's in this project?" — file tree, counts, sizes by type | `basePath` |
| `repomind_get_dependencies` | "What does this file import, directly and transitively?" | `targetPath` |
| `repomind_generate_diagram` | "Draw me the architecture" — Mermaid diagram grouped by folder | `scopePaths` (optional) |
| `repomind_impact_analysis` | "What breaks if I change this file?" — reverse dependency BFS | `targetPath`, `depth` |

All paths are absolute and everything runs against your local filesystem — `node_modules`, `.git`, `dist`, and other build/binary noise is ignored automatically. Supports JavaScript, TypeScript, and Python import resolution.

Under the hood, a single in-memory dependency graph (keyed by file `mtime`, see [`src/cache.ts`](src/cache.ts)) backs all four tools, so repeated calls on an unchanged workspace are fast.

### Also exposed

- **Resource** `repomind://workspace/graph` — the full serialized dependency graph as JSON, for clients that want to inspect it directly rather than calling a tool.
- **Prompts** `architecture-review` and `blast-radius-check` — pre-built prompt templates that pull in the live file tree / impact analysis so the assistant reviews your actual code, not a hypothetical one.

## Local Development

Only needed if you're modifying RepoMind-MCP itself — most users just want the Quick Start above.

```bash
npm install
npm run build   # compiles src/ (TypeScript) -> dist/ (ESM)
npm start        # runs the server on stdio
```

Point your client at the compiled entry point instead of npx:

```json
{
  "mcpServers": {
    "repomind-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/RepoMind-MCP/dist/index.js"]
    }
  }
}
```

### Testing

`scratch/test-server.js` spins up the built server and drives it through a handful of JSON-RPC tool calls end-to-end:

```bash
npm run build && node scratch/test-server.js
```

## License

MIT