# RepoMind 🧠

[![TypeScript](https://img.shields.io/badge/TypeScript-Strict%20v5-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-SDK%20v2.0-purple.svg)](https://modelcontextprotocol.io/)
[![Vitest](https://img.shields.io/badge/Tested%20with-Vitest-yellow.svg)](https://vitest.dev/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

**RepoMind** is a production-quality [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides AI coding assistants (such as Claude Code, Cursor, and Windsurf) with structured, bounded, and defensive intelligence about software repositories.

Rather than dumping raw directory trees or unvetted file dumps into client context windows, RepoMind analyzes repository topology, enforces robust security sandboxing, inspects dependency manifests, evaluates Git revision churn, calculates transparent heuristic health scores, and enables safe GitHub issue workflows.

---

## Why RepoMind Exists

Large language model (LLM) coding agents frequently struggle with:

1. **Context Bloat**: Feeding multi-megabyte directories or bundled minified files directly into context windows.
2. **Security Leakage**: Accidentally reading `.env` files, SSH keys, or cloud credentials during autonomous repository scans.
3. **Superficial Project Context**: Lacking high-level architectural awareness (such as high-churn hotspot files, misplaced dependencies, or lack of test density).
4. **Accidental Duplicate Issues**: Creating unvetted remote GitHub issues without checking existing records.

RepoMind solves these challenges by acting as a hardened analytical intelligence layer between your AI assistant and your local or remote codebases.

---

## Architecture

RepoMind adheres to a layered architecture that strictly separates MCP transport bindings from repository analysis engines and security sandboxing.

```mermaid
graph TD
    Client["AI Assistant / MCP Client (e.g. Claude Code)"]

    subgraph RepoMind ["RepoMind MCP Server"]
        Transport["Stdio Transport (JSON-RPC 2.0)"]
        Dispatcher["McpServer Dispatcher"]

        subgraph SecurityBoundary ["Security & Sandboxing Layer"]
            PathVal["Path Traversal & Symlink Sandbox"]
            Filter["Sensitive File & Key Blocker"]
            Sniffer["Binary Content & Size Limiter"]
        end

        subgraph ToolAdapters ["Tool Adapters"]
            T_Overview["get_project_overview"]
            T_File["get_file"]
            T_Search["search_code"]
            T_Structure["analyze_structure"]
            T_Deps["analyze_dependencies"]
            T_Git["git_history"]
            T_Report["analyze_project"]
            T_GhSearch["search_github_issues"]
            T_GhCreate["create_github_issue"]
        end

        subgraph AnalysisEngines ["Analysis Engines"]
            Scanner["RepositoryScanner"]
            Searcher["CodeSearcher"]
            DepAnalyzer["DependencyAnalyzer"]
            GitAnalyzer["GitAnalyzer"]
            HealthScorer["HealthScorer"]
            GhService["GitHubService"]
        end
    end

    LocalFS[("Sandboxed Local Repository")]
    GitCLI["Git CLI (execFile, no-shell)"]
    GitHubAPI["GitHub REST API"]

    Client <--> |stdio| Transport
    Transport <--> Dispatcher
    Dispatcher --> ToolAdapters
    ToolAdapters --> SecurityBoundary
    SecurityBoundary --> AnalysisEngines
    AnalysisEngines <--> LocalFS
    AnalysisEngines <--> GitCLI
    AnalysisEngines <--> GitHubAPI
```

---

## Key Features

- 🛡️ **Defensive Path Sandboxing**: Prevents `../` traversal, URL-encoded path attacks, absolute-path escapes, and symlink directory breakouts.
- 🔒 **Sensitive File & Credential Shield**: Automatically denies access to `.env`, `.env.*`, `credentials.json`, `*.pem`, `*.key`, `id_rsa`, `id_ed25519`, and cloud configuration folders (`.aws/`, `.kube/`). Permits safe public templates like `.env.example`.
- 📦 **Binary Content Detection**: Sniffs the first 1024 bytes of files for null bytes (`0x00`) and excessive control characters to prevent binary corruption in LLM context.
- 🔍 **Bounded Code Search**: Recursively searches source code with customizable surrounding context lines, automatically ignoring `.git`, `node_modules`, `dist`, `coverage`, and temporary build directories.
- 📊 **Static Dependency Audit**: Discovers duplicate resolved package versions, flags misplaced development tooling declared in production dependencies, and identifies unused candidate dependencies.
- 📈 **Git Churn & Hotspot Analysis**: Safely invokes Git CLI to uncover files with high revision frequency and active author distributions without shell execution vulnerabilities.
- 🎯 **Transparent Heuristic Health Scoring (0–100)**: Evaluates architecture, maintainability, dependencies, testing, and security hygiene with explicit mathematical point contributions and actionable recommendations.
- 🐙 **Safe Two-Step GitHub Issue Integration**: Enforces automated duplicate preflight checks before creating remote GitHub issues.

---

## MCP Tool Reference

RepoMind exposes 10 tools to MCP clients:

| Tool Name              | Description                                                                                      | Key Inputs                                                                                    |
| :--------------------- | :----------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- |
| `ping`                 | Verifies server connectivity, uptime, version, and Node runtime.                                 | `message?: string`                                                                            |
| `get_project_overview` | High-level summary of languages, frameworks, package managers, and entry points.                 | `repositoryPath: string`                                                                      |
| `get_file`             | Sandboxed file content reader with line count, size limits, and binary checks.                   | `repositoryPath: string`, `relativePath: string`                                              |
| `search_code`          | Recursive, bounded source code text search with surrounding context lines.                       | `repositoryPath: string`, `query: string`, `fileExtensions?: string[]`, `maxResults?: number` |
| `analyze_structure`    | Hierarchical directory tree, file type breakdown, largest files and directories.                 | `repositoryPath: string`, `maxDepth?: number`                                                 |
| `analyze_dependencies` | Audits manifests and lockfiles for duplicate packages and misplaced dev dependencies.            | `repositoryPath: string`                                                                      |
| `git_history`          | Commits, active authors, and code churn hotspots. Gracefully handles non-git repos.              | `repositoryPath: string`, `maxCommits?: number`                                               |
| `analyze_project`      | **Showcase tool**: Synthesizes a unified engineering report with health score.                   | `repositoryPath: string`                                                                      |
| `search_github_issues` | Searches existing issues in a GitHub repository to prevent duplicates.                           | `owner: string`, `repo: string`, `query: string`, `state?: "open"\|"closed"\|"all"`           |
| `create_github_issue`  | Creates a new GitHub issue. Enforces preflight duplicate check if `confirmCreate` is not `true`. | `owner: string`, `repo: string`, `title: string`, `body: string`, `confirmCreate?: boolean`   |

---

## Installation

### Prerequisites

- Node.js `v20.0.0` or higher
- Git installed on system path

### Clone and Build

```bash
git clone https://github.com/your-username/repomind.git
cd repomind
npm install
npm run build
```

---

## Configuration

Copy `.env.example` to `.env` if using GitHub issue integration:

```bash
cp .env.example .env
```

Set your personal access token:

```env
GITHUB_TOKEN=ghp_yourPersonalAccessTokenHere
```

_Note: GitHub integration is optional. Local repository inspection tools function completely without any environment variables or network access._

---

## Claude Code Integration

To integrate RepoMind with **Claude Code** or the **Claude Desktop** application, add RepoMind to your MCP server configuration:

### Configuration in `claude_desktop_config.json`

```json
{
  "mcpServers": {
    "repomind": {
      "command": "node",
      "args": ["/path/to/repomind/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_optional_token"
      }
    }
  }
}
```

_On Windows, use absolute paths:_

```json
{
  "mcpServers": {
    "repomind": {
      "command": "node",
      "args": ["D:\\MCP Server Project\\dist\\index.js"]
    }
  }
}
```

---

## Usage Examples

### 1. Maintainability Audit Walkthrough

**User:** _"Analyze this repository and identify the three biggest maintainability problems."_

**Claude's Execution Flow:**

1. Calls `get_project_overview` to understand languages and framework conventions.
2. Calls `analyze_structure` to find oversized files and directory sprawl.
3. Calls `git_history` to locate high-churn files that change frequently.
4. Synthesizes a grounded report highlighting volatile hotspot modules and file size distribution.

### 2. Comprehensive Health Assessment

**User:** _"Run a full architecture and health inspection on my codebase."_

**Claude calls:** `analyze_project` with `{ "repositoryPath": "." }`
**Output snippet:**

```json
{
  "repositoryName": "demo-project",
  "executiveSummary": "RepoMind analyzed repository 'demo-project' (4 files). The project scored 88/100 in heuristic health with strongest performance in architecture and highest improvement potential in dependencies.",
  "healthScore": {
    "overall": 88,
    "categories": {
      "architecture": 100,
      "maintainability": 90,
      "dependencies": 70,
      "testing": 100,
      "security": 100
    },
    "findings": [
      {
        "category": "dependencies",
        "type": "warning",
        "impactPoints": -10,
        "title": "Suspicious or Misplaced Dependencies",
        "description": "Detected 1 dependency issue(s), including: Package '@types/node' is a build/type/test tool but is declared in production 'dependencies'.",
        "recommendation": "Move '@types/node' to 'devDependencies'."
      }
    ]
  }
}
```

### 3. Safe GitHub Issue Reporting

**User:** _"File a GitHub issue for this maintainability problem."_

**Claude's Safe Workflow:**

1. Claude calls `create_github_issue` with `{ "owner": "myorg", "repo": "myapp", "title": "Move @types/node to devDependencies", "body": "...", "confirmCreate": false }`.
2. RepoMind runs a preflight duplicate check and returns:
   ```json
   {
     "status": "confirmation_required",
     "message": "Preflight check completed with no existing duplicate issues detected. To proceed and create this issue, invoke create_github_issue again with 'confirmCreate: true'.",
     "similarIssues": []
   }
   ```
3. Claude asks the user: _"No duplicate issues found. Would you like me to proceed with creating this issue?"_
4. User responds: _"Yes, create it."_
5. Claude calls `create_github_issue` with `"confirmCreate": true`.

---

## Security Model & Sandboxing

RepoMind treats all repository paths supplied by clients as untrusted:

1. **Sandboxed Root Containment**: Every relative path is resolved and validated to ensure the resulting canonical physical path (`fs.realpathSync.native`) cannot escape the designated repository root.
2. **Path Traversal Rejection**: Rejects `../`, `..\`, null bytes `\0`, and encoded traversal sequences (`%2e%2e`).
3. **Sensitive File Denylist**: Intercepts requests for `.env`, `credentials.json`, `secrets.json`, SSH keys (`id_rsa`, `id_ed25519`), certificates (`*.pem`, `*.key`, `*.pfx`), and cloud directories (`.aws`, `.kube`).
4. **Binary Content Sniffing**: Automatically identifies binary files by extension and header byte inspection, returning structured errors instead of corrupting model memory.
5. **No Shell Execution**: Git commands execute directly using `execFile` with immutable argument arrays, eliminating shell injection vectors.
6. **Stdio Protocol Hygiene**: All logging, diagnostics, and errors write strictly to `stderr`. `stdout` is dedicated exclusively to valid JSON-RPC 2.0 frames.

---

## Testing

RepoMind maintains a strict test suite powered by Vitest, covering path sandboxing, search bounding, dependency analysis, Git history, and MCP tool handlers:

```bash
# Run unit and integration tests
npm test

# Run TypeScript compiler
npm run build

# Run ESLint (Strict, zero-any rule)
npm run lint

# Run Prettier code formatting check
npm run format
```

---

## Project Structure

```
repomind/
├── src/
│   ├── index.ts                # Stdio transport entry point & signal handling
│   ├── server/
│   │   └── createServer.ts     # McpServer initialization & tool registrations
│   ├── tools/                  # MCP tool definitions & schema validation
│   │   ├── ping.ts
│   │   ├── projectOverview.ts
│   │   ├── getFile.ts
│   │   ├── searchCode.ts
│   │   ├── analyzeStructure.ts
│   │   ├── analyzeDependencies.ts
│   │   ├── gitHistory.ts
│   │   ├── analyzeProject.ts
│   │   └── githubIssues.ts
│   ├── services/               # Core analytical business logic
│   │   ├── repositoryScanner.ts
│   │   ├── codeSearcher.ts
│   │   ├── dependencyAnalyzer.ts
│   │   ├── gitAnalyzer.ts
│   │   ├── healthScorer.ts
│   │   ├── projectAnalyzer.ts
│   │   └── githubService.ts
│   ├── security/               # Defensive path & file sandboxing
│   │   ├── limits.ts
│   │   ├── pathValidator.ts
│   │   └── sensitiveFiles.ts
│   ├── types/                  # Strict TypeScript interfaces
│   │   ├── server.ts
│   │   ├── repository.ts
│   │   ├── analysis.ts
│   │   └── github.ts
│   └── utils/                  # Shared formatting & ignore helpers
│       ├── fileUtils.ts
│       └── ignorePatterns.ts
├── tests/                      # Vitest test suites (12 files, 70+ tests)
├── examples/
│   └── demo-project/           # Sample runnable codebase for verification
├── docs/
│   └── architecture.md         # Detailed design specification
├── package.json
├── tsconfig.json
├── eslint.config.js
├── prettier.config.js
└── LICENSE
```

---

## Limitations

- **Heuristic Nature**: Health scoring is a heuristic estimation based on structural indicators; it is not a certified compliance audit or formal security verification.
- **Vulnerability Data**: Static dependency analysis detects misplaced tooling and duplicate tree versions, but does not query active CVE vulnerability databases.
- **Language Deep Inspection**: Abstract Syntax Tree (AST) parsing is not currently implemented; import detection relies on high-speed regex pattern matching.

---

## Future Improvements

- [ ] AST-based import resolution using `@babel/parser` or Tree-sitter for non-JavaScript languages.
- [ ] Integration with OSV / GitHub Advisory Database for direct CVE vulnerability lookups.
- [ ] Support for Monorepos with multiple workspace packages (pnpm workspaces, Turborepo).
- [ ] Optional Streamable HTTP transport mode for remote deployment.

---

## License

MIT © RepoMind Contributors. See [LICENSE](LICENSE) for details.