Repository Analyzer MCP Server

A Model Context Protocol (MCP) server that provides tools for analyzing code repositories, with a special focus on Nostr-related projects.

Features

• Analyze code structure, components, dependencies, and recent changes
• Search through repository code with pattern matching
• View git history for the entire repository or specific files
• Access file content and directory listings
• Special tools for analyzing NDK (Nostr Development Kit) repositories
• Analyze Nostr Protocol implementations and NIPs (Nostr Implementation Possibilities)

Installation

1. Clone this repository

2. Install dependencies:

npm install

3. Build the project:

npm run build

Usage

Setting the Repository Path

The MCP server handles file paths in the following ways:

Default Access Behavior

1. Default access: By default, the server will access the current working directory (cwd) if no path is specified.

2. Configure specific directories: To specify what directories Claude can access, set the DEFAULT_REPO_PATH environment variable in the Claude config.

3. Per-command overrides: Users can override the default path with the repoPath parameter in their commands, like:

   analyze-code --focus=structure --repoPath=/another/directory
   

4. Client permissions: Remember that Claude for Desktop will ask for permission before executing tools that access your filesystem.

Analyzing Multiple Repositories

You can analyze multiple repositories without restarting the server by specifying the repository path directly in your commands:

# Analyze structure of a specific repository
analyze-repo --focus=overview --repoType=generic --repoPath=/path/to/specific/repo

# Analyze code in a different repository
analyze-code --focus=structure --path=src/index.js --repoPath=/path/to/another/repo

# Search for patterns in yet another repository
search-code --query="addEventListener" --filePattern="*.js" --repoPath=/path/to/third/repo

All analysis tools (analyze-repo, analyze-code, search-code, git-history, analyze-ndk, analyze-ndk-files, and analyze-nostr-protocol) accept a repoPath parameter which overrides the default path.

Connecting to Claude Desktop

To connect this MCP server to Claude Desktop:

1. Edit your Claude Desktop config file:

# On macOS
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
# On Windows
# Edit %AppData%\Claude\claude_desktop_config.json

2. Add the server configuration:

{
  "mcpServers": {
    "repo-analyzer": {
      "command": "node",
      "args": [
        "/absolute/path/to/repo-analyzer-mcp/dist/index.js"
      ],
      "transport": "stdio",
      "env": {
        "NODE_ENV": "production",
        "DEFAULT_REPO_PATH": "/path/to/default/repository"
      }
    }
  }
}

Replace /absolute/path/to/repo-analyzer-mcp with the actual full path to where you installed this tool, and /path/to/default/repository with the path to the repository you want to analyze by default.

3. Save the file and restart Claude Desktop.

Troubleshooting

If Claude Desktop fails to start or the MCP servers don't appear:

1. Check your configuration file for JSON syntax errors
2. Ensure all paths are absolute (full) paths and are correct
3. Make sure there are no trailing commas after the last entry in each object
4. Check Claude Desktop logs for errors: ~/Library/Logs/Claude/mcp*.log
5. For additional debugging, you can add "DEBUG": "mcp:*" to the env section of your configuration
6. Restart Claude Desktop

Available Tools

analyze-code

Analyzes code files with different focus options:

• structure: Examines the file structure, including line counts, functions, classes, etc.
• components: Identifies React components, hooks usage, etc.
• dependencies: Lists imports and dependencies
• changes: Shows recent git history and changes to the file

Example:

Analyze the code structure of src/index.ts

search-code

Searches the repository for specific patterns, with optional file pattern filtering.

Example:

Search the code for "addEventListener" in .js files

git-history

Retrieves git commit history for the repository or a specific file.

Example:

Show me the git history for README.md, limit to 5 commits

analyze-ndk

Analyzes Nostr Development Kit (NDK) repositories with focus on:

• implementation: Core implementation details
• migrations: Version changes and migration guides
• all: Both implementation and migrations

Example with explicit repository path:

Analyze NDK implementation at /path/to/ndk-repo

analyze-ndk-files

Explores the NDK file structure with focus on:

• overview: General overview of the repository
• components: Component architecture
• api: API structure and design
• architecture: Overall architecture and patterns
• all: Comprehensive analysis

Example with explicit repository path:

Analyze NDK files with focus on components at /path/to/ndk-repo

analyze-nostr-protocol

Analyzes Nostr protocol repositories with focus on:

• events: Event types and structures defined in NIPs
• implementations: Implementation details across different languages

Example with explicit repository path:

Analyze Nostr Protocol events at /path/to/nips-repo with focus on social context

analyze-repo

Provides a general repository analysis with various focus options:

• overview: High-level repository information
• components: Component structure and organization
• api: API definitions and structure
• architecture: Overall architectural patterns
• implementation: Implementation details
• all: Comprehensive analysis of all aspects

Example:

Analyze the repo with focus on architecture

Resources

The server also provides access to:

• file://{filePath}: Read file contents from the repository
• dir://{dirPath}: List directory contents from the repository

Example:

Show me the content of the package.json file

Directory Structure for Specialized Analysis

For the specialized analysis tools to work correctly, repositories should follow certain structures:

NDK Repository Structure

The analyzer looks for one of these structures:

• A repository with a root package.json that has the name @nostr-dev-kit/ndk
• A repository with an ndk directory containing a package.json with the name @nostr-dev-kit/ndk

Nostr Protocol Repository Structure

The analyzer looks for one of these structures:

• A repository with a nips directory containing Markdown files for NIPs
• A repository with a README mentioning "NIP" and "Nostr Implementation Possibilities"
• A repository with a package.json that references "nostr" in its name, description, or keywords

Development

To run in development mode:

npm run dev

License

MIT