🚀 ZOD MCP Server

Интеллектуальный MCP‑сервер с индексированием кода, семантическим поиском и набором инструментов.

📖 Overview

ZOD MCP Server — сервер по спецификации MCP (Model Context Protocol) с возможностями индексирования проектов, гибридного поиска (текст + векторы) и расширяемыми инструментами.

🏗️ Architecture

Core Components

src/
├── core/                    # Core business logic
│   ├── indexer.ts          # Project indexing engine
│   ├── vector-search.ts    # Vector search and embeddings
│   ├── database.ts         # Database management
│   ├── search.ts           # Hybrid search engine
│   ├── project-analyzer.ts # Code analysis and metrics
│   └── config-manager.ts   # Configuration management
├── tools/                   # MCP tool implementations
│   ├── zod-core/           # Core ZOD tools
│   ├── documentation/      # Documentation tools
│   ├── repository/         # Repository management
│   └── unified-search/     # Web and deep research
├── domains/                 # Domain-specific logic
├── application/             # Application services
├── presentation/            # API and interface layers
└── shared/                  # Shared utilities and types

Data Flow

Project Input → Indexer → Database + Vector Store → Search Engine → Results
     ↓              ↓              ↓                    ↓
  File Scan    Content Parse   Embedding Gen    Hybrid Search
     ↓              ↓              ↓                    ↓
  Language     Metadata      Vector Storage    Semantic + Text
  Detection    Extraction    Indexing        Results Ranking

🚀 Features

🔍 Intelligent Indexing

• Multi-language support (TypeScript, JavaScript, Python, etc.)
• Smart file filtering (excludes build artifacts, dependencies)
• Incremental updates with change detection
• Parallel processing for large projects

🧠 Vector Search

• Semantic code search using embeddings
• Multiple embedding models (OpenAI, local alternatives)
• Hybrid search combining vector and text search
• Context-aware results with relevance scoring

📊 Code Analysis

• Quality metrics calculation
• Maintainability scoring
• Test coverage analysis
• Performance profiling

🔧 MCP Integration

• Standard MCP protocol compliance
• Multiple transport modes (HTTP, SSE, stdio)
• Extensible tool system
• Plugin architecture

🛠️ Installation

Prerequisites

• Node.js 18+
• npm or yarn
• Git

Quick Start

# Clone
 git clone https://github.com/NURJAKS/ZOD-mcp-server.git
 cd ZOD-mcp-server

# Install JS deps and build
npm install
npm run build

# Link CLI binaries (zod-mcp)
npm link

Environment Configuration

Create a .env file in the project root:

# API Keys
OPENROUTER_API_KEY=your_openrouter_key
QDRANT_URL=your_qdrant_url
QDRANT_API_KEY=your_qdrant_key

# Vector Search
EMBEDDING_MODEL=openai/text-embedding-3-large
EMBEDDING_MODEL_HINT=openai/text-embedding-3-large

# Performance
MAX_FILE_SIZE=1048576
CONCURRENCY_LIMIT=5

📚 Usage

Command Line Interface (MCP server)

# stdio (для MCP‑клиентов, например Cursor)
zod-mcp --stdio

# HTTP транспорт
zod-mcp --http --port 3000 --endpoint /mcp

# SSE транспорт
zod-mcp --sse --port 3001

MCP Tools

The server provides several MCP tools:

Core Tools

• core-index - Project indexing and analysis
• core-search - Code search and exploration
• core-analyze - Code quality analysis
• core-fix - Automated code fixes
• core-status - System status and metrics

Research Tools

• documentation - Documentation indexing and search
• repository - Repository management
• unified-search - Web and deep research
• visualizer - Code visualization

Example Usage

// Index a project
const result = await mcp.tools['core-index'].index({
  path: '/path/to/project',
  options: {
    enableVectorSearch: true,
    maxFileSize: 1024 * 1024,
    includeExtensions: ['.ts', '.js', '.py']
  }
})

// Search for code
const searchResults = await mcp.tools['core-search'].search({
  query: 'function authentication',
  type: 'semantic',
  limit: 10
})

🔧 Development

Project Structure

├── src/                    # Source code
│   ├── core/              # Core business logic
│   ├── tools/             # MCP tool implementations
│   ├── domains/           # Domain-specific logic
│   ├── application/       # Application services
│   ├── presentation/      # API and interface layers
│   └── shared/            # Shared utilities
├── tests/                 # Test files
├── scripts/               # Build and utility scripts
├── docs/                  # Documentation
└── examples/              # Usage examples

Development Commands

# Development mode with hot reload
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint
npm run lint:fix

# Testing
npm run test
npm run test:coverage
npm run test:watch

# Build
npm run build

Testing Strategy

• Unit tests for individual components
• Integration tests for MCP tools
• Performance tests for large projects
• Coverage target: 90%+

📊 Performance

Benchmarks

• Indexing speed: ~1000 files/minute
• Search response: <100ms for typical queries
• Memory usage: ~50MB base + 10MB per 1000 files
• Vector search: <200ms for semantic queries

Optimization Features

• Parallel processing for large projects
• Incremental updates to avoid re-indexing
• Smart caching for frequently accessed data
• Connection pooling for database operations

🔒 Security

Security Features

• Environment variable configuration
• API key management with secure storage
• Input validation and sanitization
• Rate limiting for external APIs
• Secure defaults for all configurations

Best Practices

• Never commit API keys to version control
• Use environment variables for sensitive data
• Regularly rotate API keys
• Monitor API usage and rate limits

🤝 Contributing

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

Code Standards

• TypeScript strict mode enabled
• ESLint configuration enforced
• Prettier formatting
• JSDoc documentation required
• Test coverage minimum 80%

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol team for the MCP specification
• OpenAI for embedding models
• Qdrant for vector database
• OpenRouter for API access

📞 Support

• Documentation: Project Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

Made with ❤️ by the ZOD Team