CodeAnalysis MCP Server

# MCP Code Analysis A powerful codebase analysis toolkit that leverages the Model Context Protocol (MCP) for AI-assisted code understanding and transformation. ## Features - **Code Analysis**: Parse and analyze codebases with abstract syntax trees - **Context Generation**: Create rich contextual information for AI models - **Tool Integration**: Built on the MCP SDK for seamless AI tool integration - **Extensible Architecture**: Plugin-based system for custom analyzers ## Requirements - Node.js 18+ - NPM 9+ - Redis (optional, only required for production environments) ## Installation ```bash # Clone the repository git clone https://github.com/yourusername/mcp-codeanalysis.git cd mcp-codeanalysis # Install dependencies npm install # Build the project npm run build ``` ## Redis Configuration (Optional) Redis is used for session storage in production environments. For development and testing, the system will automatically fall back to an in-memory session store if Redis is not available. > **Note**: There is a known issue with Redis connectivity where operations may fail even when Redis is running. See the "Tech Debt" section in `plan.md` for details. For now, you can use the `./use-memory-session.sh` script to run the server with the memory session store. For more information, see [Redis Troubleshooting Guide](./docs/redis-troubleshooting.md). To install Redis: ```bash # Ubuntu/Debian sudo apt-get install redis-server # macOS brew install redis # Windows (using WSL is recommended) # For native Windows, download from https://redis.io/download ``` By default, the application tries to connect to Redis at `redis://localhost:6379`. You can configure the Redis connection using environment variables: ```bash # Set custom Redis URL export REDIS_URL=redis://custom-host:6379 # Force memory session store even if Redis is available export FORCE_MEMORY_SESSION=true ``` ## Development ```bash # Run in development mode npm run dev # Run tests npm test # Run linting npm run lint ``` ## Usage ```bash # Start the MCP server npm start # Run CLI tool node ./tools/mcp-stdio-client.js --task "Analyze dependencies" --files "src/*.ts" ``` ## Documentation - [Session Store Architecture](./docs/session-store.md) - [Redis Integration](./docs/redis-integration.md) - [MCP Protocol](./docs/mcp-protocol.md) ## License MIT # CodeAnalysis MCP Server A comprehensive Model Context Protocol (MCP) server for advanced code analysis, providing tools and insights through an extensible architecture. ## 🚀 Features - **Basic Code Analysis**: Syntax and structure analysis - **Code Metrics**: Complexity, line counts, and code quality metrics - **Dependency Analysis**: Package and import relationship visualization - **Knowledge Graph**: Code relationships visualization and querying - **Memory System**: Store and retrieve insights about codebases - **Visualizations**: Generate diagrams in multiple formats (Mermaid, DOT, ASCII) - **Socio-Technical Analysis**: Understand team and code relationships - **Multi-Repository Analysis**: Cross-repository relationship analysis - **Evolution Planning**: Code improvement recommendations - **Live Watching**: Monitor code changes in real-time - **IDE Integration**: Tools for editor integration - **Developer Tools**: Enhanced AI-assisted development workflow support ## 📋 Prerequisites - Node.js 18+ - npm or yarn - Redis (optional for development, recommended for production) ## 🛠️ Installation ```bash # Clone the repository git clone https://github.com/your-username/codeanalysis-mcp.git cd codeanalysis-mcp # Install dependencies pnpm install # Build the project pnpm build ``` ## 🖥️ Usage The CodeAnalysis MCP server can be used in two ways: ### 1. As an MCP Server ```bash # Start the MCP server pnpm start ``` This starts the MCP server that can be connected to by any MCP client like Claude Desktop, Cursor, or others. ### 2. Using the CLI The project includes a comprehensive CLI for direct interaction: ```bash # Get help pnpm run cli --help # Analyze a repository or directory pnpm run cli analyze repo ./src # Check code quality pnpm run cli quality analyze ./src ``` ### 3. Using Developer Tools for AI-Assisted Development The project includes special tools designed to enhance AI-assisted development: ```bash # Generate code context for AI assistants node tools/ai-dev-helper.js --task="Implement new feature" --search="related functionality" # Run example client node examples/dev-tools-client.js ``` See the [Developer Tools Guide](docs/dev-tools-guide.md) for detailed information. ## 📊 Example Commands ### Basic Analysis ```bash # Analyze a local directory pnpm run cli analyze repo ./src # Analyze a specific file pnpm run cli analyze file ./src/server.ts ``` ### Code Metrics ```bash # Get code metrics with function details pnpm run cli metrics analyze ./src --functions # Save metrics to a file pnpm run cli metrics analyze ./src -o metrics-report.json ``` ### Dependency Analysis ```bash # Analyze dependencies in Mermaid format pnpm run cli dependencies analyze ./src -f mermaid -o deps.mmd # Visualize dependencies pnpm run cli visualize dependencies -p ./src --format mermaid ``` ### Code Quality ```bash # Run quality analysis pnpm run cli quality analyze ./src # Generate HTML report pnpm run cli quality analyze ./src --html -o quality-report.html ``` ### Knowledge Graph ```bash # Build knowledge graph pnpm run cli knowledge build ./src # Query the knowledge graph pnpm run cli knowledge query ./src "type:function AND complexity>5" # Export as diagram pnpm run cli knowledge export ./src -f mermaid ``` ### Insights & Memory ```bash # Store an insight pnpm run cli insights store -r ./src -t code-pattern -c "Refactoring opportunity" # Retrieve insights pnpm run cli insights retrieve -r ./src ``` ### Developer Tools ```bash # Prepare context for AI interactions node tools/ai-dev-helper.js --task="Fix authentication bug" --files="src/auth/*.ts" --search="login" # Use with AI prompts # Copy content from the generated ai-context.json file into your AI assistant prompt # or use the template in templates/ai-prompt-template.md ``` ## 🏗️ Architecture The project follows the MCP architecture with these components: 1. **MCP Server**: Core server implementation using the MCP protocol 2. **Analysis Features**: Modular code analysis capabilities 3. **CLI**: Command-line interface for direct interaction 4. **Transport Layer**: Communication mechanism (stdio by default) ## 🔌 Integration with MCP Clients This server is compatible with any MCP-compliant client, including: - Claude Desktop App - Cursor Editor - Continue - Other MCP-compatible tools ## 📝 Path Specification Commands accept paths in various formats: - Local directory: `./src` or `/absolute/path/to/dir` - Local file: `./src/file.ts` or `/path/to/file.ts` - Repository URL: `https://github.com/username/repo` ## 🤝 Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## 📄 License This project is licensed under the MIT License - see the LICENSE file for details. # MCP SDK State Management Architecture This project implements stateful tools for the Model Context Protocol (MCP) SDK, providing a framework for building tools that maintain context between invocations. ## Architecture Overview The state management architecture is organized into several modular components: ``` src/state/ ├── helpers/ │ └── statefulTool.ts # Main entry point for stateful tool creation ├── machines/ │ └── toolMachine.ts # XState machine for tool execution flow ├── services/ │ ├── toolService.ts # Core execution service for tools │ ├── redisToolExecutionService.ts # Distributed execution service │ ├── redisSessionStore.ts # Redis-based session persistence │ └── types.ts # Shared type definitions ``` ## Core Components ### Stateful Tool Helper (`statefulTool.ts`) The central integration point with the MCP SDK, providing: - Tool registration with session management - MCP-compliant response formatting - In-memory session management - Helper functions for session access and manipulation ```typescript // Creating a stateful tool with state persistence createStatefulTool(server, "my-tool", schema, handler); // With description createStatefulTool(server, "my-tool", "My stateful tool", schema, handler); ``` ### Tool Machine (`toolMachine.ts`) XState-based state machine that defines the execution flow for tools: - State transitions (idle, toolSelected, parametersSet, executing, etc.) - Context management for parameters, results, and history - Error handling and recovery paths This component delegates session management to the statefulTool implementation. ### Tool Service (`toolService.ts`) Core execution service that coordinates tool state transitions: - Manages tool selection, parameter validation, and execution - Tracks execution history - Handles execution results and errors ### Types (`types.ts`) Shared type definitions that ensure consistency across the state management system: - SessionData: Structure for storing tool state - SessionStore: Interface for session storage implementations - ExecutionResult: Standard response format for tools ## Integration with MCP SDK The architecture integrates with the MCP SDK by: 1. Extending the tool registration pattern with state management 2. Maintaining compatibility with MCP's response format 3. Providing session and context tracking for stateful operations ## Usage Example ```typescript import { createServer } from "@modelcontextprotocol/sdk"; import { createStatefulTool } from "./state/helpers/statefulTool"; import { z } from "zod"; const server = createServer(); // Register a stateful tool createStatefulTool( server, "counter", "A tool that maintains a count between invocations", { action: z.enum(["increment", "decrement", "reset"]), }, async (params) => { // Get session ID from params (or a new one will be created) const sessionId = params.sessionId; // Process the action let count = 0; // Tool logic with state manipulation... return { count }; } ); server.listen(3000); ``` ## Distributed State Management For distributed environments, the Redis-based implementations provide: - Session persistence across server restarts - Distributed locking for concurrent access - TTL-based session cleanup - Error handling for network/connection issues ## Testing The components include comprehensive test suites to verify: - Tool state transitions - Session management - Error handling and recovery - Response formatting - Distributed operation (with Redis) ## AI Development Tools The CodeAnalysis MCP Server provides specialized tools for AI-assisted development. These tools help collect code context that can be fed to AI systems for more effective assistance. ### Client Scripts The repository includes several client scripts in the `tools/` directory: - **HTTP Client** (`tools/http-client.js`): Connects to the MCP server via HTTP transport (default). ```bash node tools/http-client.js --task "Your task description" --files "src/features/*.ts" --search "session" ``` - **Raw Client** (`tools/mcp-raw-client.js`): A simpler client that only captures server information. ```bash node tools/mcp-raw-client.js --task "Your task description" ``` - **Simple Client** (`tools/simple-client.js`): Communicates with the server via stdio. ```bash node tools/simple-client.js --task "Your task description" --files "src/features/*.ts" ``` All client scripts generate an `ai-context.json` file in the project root. This file contains valuable context about your codebase that can be shared with AI assistants to provide better-informed responses. ### Prompt Template A prompt template for AI assistants is available at `templates/ai-prompt-template.md`. This template helps structure your requests to AI assistants with proper context from the MCP tools. ### Server Transport Modes The MCP server supports two transport modes: 1. **HTTP Transport** (default): Runs on port 3000 by default. Best for client-server architecture. 2. **Stdio Transport**: For direct process communication. Set the `STDIO_TRANSPORT=true` environment variable to enable. ## Session Storage Architecture MCP Code Analysis now features a modular session store architecture with automatic backend detection: - **Flexible Storage**: Automatically switches between Redis and in-memory storage - **Development Friendly**: Run without Redis during development - **Production Ready**: Use Redis for persistence in production environments - **Automatic Fallback**: Gracefully falls back to memory storage when Redis is unavailable For more details, see the [Session Store Architecture](docs/session-store.md) documentation. ## Requirements - Node.js 18+ - npm or yarn - Redis (optional for development, recommended for production)