使用说明

DevMCP - MCP Codebase Analyzer

DevMCP is an AI-powered codebase analysis tool that uses Model Context Protocol (MCP), Pinecone vector database, and DeepSeek-R1 LLM to analyze code repositories. It can ingest codebases, perform semantic search, and generate detailed analysis reports.

Features

🔍 Repository Ingestion: Scan and index code repositories into Pinecone vector database
📊 Semantic Search: Query codebases using natural language questions
🤖 AI Analysis: Analyze code using DeepSeek-R1 LLM for architecture insights, issues, and recommendations
📝 Report Generation: Generate comprehensive Markdown reports with findings and recommendations
🐳 Docker Support: Easy deployment with Docker Compose
🌐 REST API: FastAPI-based REST API for programmatic access
🔌 MCP Server: Model Context Protocol server for integration with AI tools

Prerequisites
Installation
Configuration
Running the Application
Usage Examples
Architecture
Environment Variables
Troubleshooting

Prerequisites

Python 3.11+ (Python 3.14 recommended)
Pinecone Account: Sign up at pinecone.io to get an API key
Ollama: For running DeepSeek-R1 locally (or use Docker Compose which includes it)
Git: For cloning repositories (if analyzing remote repos)

Optional Prerequisites

Docker & Docker Compose: For containerized deployment
Virtual Environment: Recommended for Python dependency isolation

Installation

1. Clone the Repository

git clone <repository-url>
cd devmcp

2. Create Virtual Environment (Recommended)

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Install Ollama (if not using Docker)

macOS:

brew install ollama

Linux:

curl -fsSL https://ollama.com/install.sh | sh

Windows: Download from ollama.com

5. Pull DeepSeek-R1 Model

ollama pull deepseek-r1:8b

Note: This model is ~5GB and may take several minutes to download.

Configuration

1. Create `.env` File

Copy the example environment file and fill in your credentials:

cp .env.example .env

Then edit .env and add your Pinecone API key:

# Pinecone Configuration
PINECONE_API_KEY=your_pinecone_api_key_here
PINECONE_INDEX=devmcp

# Embedding Model (default: BAAI/bge-small-en-v1.5)
EMBEDDING_MODEL=BAAI/bge-small-en-v1.5

# LLM Configuration
LLM_MODEL=deepseek-r1:8b
OLLAMA_BASE_URL=http://localhost:11434

Important: Never commit your .env file to version control. It contains sensitive credentials.

2. Get Pinecone API Key

Sign up at pinecone.io
Create a new project
Copy your API key from the dashboard
Paste it into the .env file

3. Verify Ollama is Running

ollama serve

Or if using Docker Compose, Ollama will start automatically.

Running the Application

DevMCP can be run in three different modes:

MCP Server

Run as a Model Context Protocol server for integration with AI tools:

python server/mcp_server.py

The MCP server exposes the following tools:

tool_read_repo: Scan a local repository
tool_chunk_repo: Split repository files into chunks
tool_upsert_pinecone: Embed and store chunks in Pinecone
tool_query_pinecone: Search Pinecone for relevant code chunks
tool_analyze_with_llm: Analyze code with DeepSeek-R1
tool_generate_report: Generate Markdown reports

Command Line Client

The CLI client provides a simple interface for ingesting and analyzing repositories.

Ingest a Repository

python client/run.py --repo /path/to/repository --ingest

This will:

Read all relevant files from the repository
Chunk the files into overlapping segments
Generate embeddings using the configured model
Store vectors in Pinecone

Example:

python client/run.py --repo ~/projects/my-app --ingest

Analyze a Repository

python client/run.py --repo /path/to/repository --query "Your analysis question"

Example:

python client/run.py --repo ~/projects/my-app --query "Find performance issues and security vulnerabilities"

Custom Output Path

python client/run.py --repo ~/projects/my-app --query "Analyze architecture" --output outputs/custom-report.md

REST API

Start the FastAPI server:

python api/main.py

Or using uvicorn directly:

uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

The API will be available at http://localhost:8000

API Endpoints

Health Check:

curl http://localhost:8000/health

Ingest Repository:

curl -X POST http://localhost:8000/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "repo_path": "/path/to/repository",
    "max_file_bytes": 100000
  }'

Analyze Repository:

curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "repo_path": "/path/to/repository",
    "query": "Find performance bottlenecks",
    "output_path": "outputs/REPORT.md",
    "top_k": 12
  }'

API Documentation: Visit http://localhost:8000/docs for interactive Swagger UI documentation.

Docker Deployment

Using Docker Compose (Recommended)

Ensure .env file exists with all required variables
Build and start services:

docker-compose up --build

This will:

Build the application container
Start Ollama service
Start the FastAPI server on port 8000
Mount the outputs directory for report persistence

Access the API:

curl http://localhost:8000/health

Stop services:

docker-compose down

Using Dockerfile Directly

# Build image
docker build -t devmcp .

# Run container
docker run -p 8000:8000 \
  --env-file .env \
  -v $(pwd)/outputs:/app/outputs \
  devmcp

Note: When using Docker, ensure OLLAMA_BASE_URL=http://ollama:11434 in your .env file (not localhost).

Usage Examples

Complete Workflow Example

# 1. Ingest a repository
python client/run.py --repo ~/projects/my-python-app --ingest

# Output:
# === INGESTING REPO ===
# [1/3] Reading repository files...
#       Repo ID: a1b2c3d4e5f6 | Files: 45
# [2/3] Chunking files...
#       Total chunks: 128
# [3/3] Embedding and storing in Pinecone...
#       Upserted: 128 vectors
# ✅ Ingestion complete! Repo ID: a1b2c3d4e5f6

# 2. Analyze the repository
python client/run.py --repo ~/projects/my-python-app \
  --query "Identify security vulnerabilities and suggest improvements"

# Output:
# === ANALYZING REPO ===
# [1/3] Querying Pinecone for: 'Identify security vulnerabilities...'
#       Retrieved 12 relevant chunks
# [2/3] Analyzing with DeepSeek-R1 (this may take 30-90 seconds)...
#       Found 5 issues
# [3/3] Generating report → outputs/REPORT.md
# ✅ Analysis complete!
#    Report saved to: outputs/REPORT.md

Example Analysis Questions

"Find all performance bottlenecks in the codebase"
"Identify security vulnerabilities and suggest fixes"
"Analyze the architecture and suggest improvements"
"Find code duplication and refactoring opportunities"
"Review error handling patterns and suggest improvements"
"Identify potential memory leaks"

Architecture

Components

Repository Reader (skills/read_repo.py)
- Scans repository files
- Filters by file extensions
- Excludes common directories (node_modules, venv, etc.)
- Generates stable repository IDs
Chunker (skills/chunk_repo.py)
- Splits files into overlapping text chunks
- Preserves metadata (file path, line numbers)
- Configurable chunk size and overlap
Vector Store (vectorstore/pinecone_client.py)
- Manages Pinecone connection
- Auto-creates index if missing
- Handles embeddings storage
Embedding (skills/upsert_pinecone.py)
- Uses sentence-transformers for embeddings
- Batch processing for efficiency
- Stores vectors with metadata in Pinecone
Query (skills/query_pinecone.py)
- Semantic search in Pinecone
- Returns top-k relevant chunks
- Includes similarity scores
LLM Analysis (skills/analyze_with_llm.py)
- Uses Ollama API to call DeepSeek-R1
- Structured JSON output
- Architecture, issues, recommendations
Report Generator (skills/generate_report.py)
- Converts analysis to Markdown
- Optional Mermaid diagrams
- Saves to specified output path

Data Flow

Repository → Read Files → Chunk → Embed → Pinecone
                                              ↓
User Query → Embed Query → Pinecone Search → LLM Analysis → Report

Supported File Types

By default, the following file types are processed:

.py (Python)
.ts, .js (TypeScript/JavaScript)
.md (Markdown)
.yml, .yaml (YAML)
.json (JSON)
.sql (SQL)
.txt (Text)
.toml (TOML)

Excluded Directories

The following directories are automatically excluded:

node_modules
venv, .venv
__pycache__
.git
dist, build
.next, .nuxt
coverage
.pytest_cache

Environment Variables

Variable	Description	Default	Required
`PINECONE_API_KEY`	Pinecone API key	-	Yes
`PINECONE_INDEX`	Pinecone index name	`devmcp`	No
`EMBEDDING_MODEL`	HuggingFace embedding model	`BAAI/bge-small-en-v1.5`	No
`LLM_MODEL`	Ollama model name	`deepseek-r1:8b`	No
`OLLAMA_BASE_URL`	Ollama server URL	`http://localhost:11434`	No

Pinecone Index Configuration

The index is automatically created with:

Dimension: 384 (for bge-small-en-v1.5)
Metric: cosine
Cloud: AWS
Region: us-east-1

Troubleshooting

Common Issues

1. Pinecone API Key Error

Error: PINECONE_API_KEY not set in .env

Solution:

Ensure .env file exists in project root
Verify PINECONE_API_KEY is set correctly
Check for extra spaces or quotes in the .env file

2. Ollama Connection Error

Error: Connection refused or Failed to connect to Ollama

Solution:

Ensure Ollama is running: ollama serve
Check OLLAMA_BASE_URL in .env
For Docker: Use http://ollama:11434 instead of localhost
Verify Ollama is accessible: curl http://localhost:11434/api/tags

3. Model Not Found

Error: model 'deepseek-r1:8b' not found

Solution:

ollama pull deepseek-r1:8b

4. Index Creation Fails

Error: Failed to create Pinecone index

Solution:

Check Pinecone account limits
Verify API key has proper permissions
Ensure index name is unique (if using shared Pinecone account)

5. Out of Memory

Error: CUDA out of memory or similar

Solution:

Reduce batch_size in upsert_pinecone calls
Use smaller embedding model (e.g., BAAI/bge-small-en-v1.5)
Process repositories in smaller batches

6. File Reading Errors

Error: Permission denied or File not found

Solution:

Ensure repository path is correct and accessible
Check file permissions
Verify path is absolute or relative to project root

7. Docker Container Issues

Error: Container fails to start or can't connect to Ollama

Solution:

Ensure docker-compose.yml is correct
Check .env file has OLLAMA_BASE_URL=http://ollama:11434
Verify Docker network: docker network ls
Check logs: docker-compose logs

Debug Mode

Enable verbose logging by setting environment variable:

export DEBUG=1
python client/run.py --repo /path/to/repo --query "test"

Performance Tips

Large Repositories: Use max_file_bytes parameter to limit file size
Batch Processing: Adjust batch_size for embedding operations
Chunk Size: Tune chunk_size and overlap for better retrieval
Top-K Results: Adjust top_k based on repository size

Project Structure

devmcp/
├── api/
│   └── main.py              # FastAPI REST API server
├── client/
│   └── run.py               # CLI client for ingestion and analysis
├── server/
│   └── mcp_server.py        # MCP server implementation
├── skills/
│   ├── read_repo.py         # Repository file reader
│   ├── chunk_repo.py        # Text chunking logic
│   ├── upsert_pinecone.py   # Embedding and vector storage
│   ├── query_pinecone.py    # Semantic search
│   ├── analyze_with_llm.py  # LLM-based analysis
│   └── generate_report.py   # Report generation
├── vectorstore/
│   └── pinecone_client.py   # Pinecone client wrapper
├── outputs/                 # Generated reports directory
├── .env                     # Environment variables (create from .env.example)
├── .env.example            # Environment variables template
├── .gitignore              # Git ignore rules
├── requirements.txt         # Python dependencies
├── Dockerfile              # Docker image definition
├── docker-compose.yml      # Docker Compose configuration
└── README.md               # This file

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Support

For issues, questions, or contributions, please open an issue or contact the maintainers.

使用说明

DevMCP - MCP Codebase Analyzer

Features

Table of Contents

Prerequisites

Optional Prerequisites

Installation

1. Clone the Repository

2. Create Virtual Environment (Recommended)

3. Install Dependencies

4. Install Ollama (if not using Docker)

5. Pull DeepSeek-R1 Model

Configuration

1. Create .env File

2. Get Pinecone API Key

3. Verify Ollama is Running

Running the Application

MCP Server

Command Line Client

Ingest a Repository

Analyze a Repository

Custom Output Path

REST API

API Endpoints

Docker Deployment

Using Docker Compose (Recommended)

Using Dockerfile Directly

Usage Examples

Complete Workflow Example

Example Analysis Questions

Architecture

Components

Data Flow

Supported File Types

Excluded Directories

Environment Variables

Pinecone Index Configuration

Troubleshooting

Common Issues

1. Pinecone API Key Error

2. Ollama Connection Error

3. Model Not Found

4. Index Creation Fails

5. Out of Memory

6. File Reading Errors

7. Docker Container Issues

Debug Mode

Performance Tips

Project Structure

Contributing

Support

相关 MCP

AI持久记忆服务器

代码索引分析工具

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

代码分析服务器

GitHub仓库解析工具

1. Create `.env` File