Content
# 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:
```bash
npm install
```
3. Build the project:
```bash
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:
```bash
# 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:
```json
{
"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:
```bash
npm run dev
```
## License
MIT
