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.

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
- Redis Integration
- MCP Protocol

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:

$3

`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.

$3

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

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 for detailed information.

📊 Example Commands

$3

`bash


Analyze a local directory

pnpm run cli analyze repo ./src

Analyze a specific file

pnpm run cli analyze file ./src/server.ts
`

$3

`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
`

$3

`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
`

$3

`bash


Run quality analysis

pnpm run cli quality analyze ./src

Generate HTML report

pnpm run cli quality analyze ./src --html -o quality-report.html
`

$3

`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
`

$3

`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
`

$3

`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

$3

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);
`

$3

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.

$3

Core execution service that coordinates tool state transitions:

- Manages tool selection, parameter validation, and execution
- Tracks execution history
- Handles execution results and errors

$3

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.

$3

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.

$3

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.

$3

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 documentation.

Requirements

- Node.js 18+
- npm or yarn
- Redis (optional for development, recommended for production)