RepoMind 🧠

RepoMind is a production-quality Model Context Protocol (MCP) 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.

Related MCP server: Code Search, Read & PR Analysis

Architecture

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

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:

Installation

Prerequisites

• Node.js v20.0.0 or higher

• Git installed on system path

Clone and Build

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:

cp .env.example .env

Set your personal access token:

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

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

On Windows, use absolute paths:

{
  "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:

{
  "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:

   {
     "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:

# 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 for details.