Semantic Context MCP

🚀 Enterprise Code Search MCP Server

This is a powerful Model Context Protocol (MCP) server designed for semantic code search, leveraging a shared vector database. It supports both OpenAI and Ollama for generating embeddings, and can index local projects or Git repositories, offering high flexibility and efficiency for enterprise code management.

🚀 Quick Start

1. Clone the repository

git clone https://github.com/your-username/semantic-context-mcp.git
cd semantic-context-mcp

2. Install dependencies

npm install

3. Configure environment

cp .env.example .env
# Edit .env with your configuration

4. Start services

# Start ChromaDB and Ollama
docker-compose up -d

# Wait for Ollama to download models
docker-compose logs -f ollama-setup

5. Build and run

npm run build
npm start

✨ Features

• Semantic code search: Utilize AI embeddings to conduct semantic code search, enabling more accurate and efficient code retrieval.
• Dual provider support: Support both OpenAI and Ollama (local, private), allowing users to choose according to their needs.
• Flexible indexing: Index local projects or Git repositories, providing multiple options for code source management.
• Shared vector database: Use ChromaDB as a shared vector database to store and manage code embeddings.
• Multi-project management: Handle multiple projects simultaneously, improving the efficiency of enterprise code management.
• Automatic project structure analysis: Automatically analyze the structure of projects, facilitating code understanding and management.
• Similar code search: Search for similar code based on code snippets, helping developers find relevant code quickly.
• Enterprise-ready: Designed for enterprise use, ensuring privacy, security, and the ability to be self - hosted.

📦 Installation

Requirements

• Node.js 18+
• Docker and Docker Compose
• Git (for repository indexing)

💻 Usage Examples

1. Index a local project

Index my local project at /home/user/my-app with the name "frontend-app"

2. Search in code

Search for "main application function" in all indexed projects

3. Find similar code

Find code similar to:
```python
def authenticate_user(username, password):
    return check_credentials(username, password)

4. Analyze project structure

Analyze the structure of project "frontend-app"

📚 Documentation

Configuration

Using Ollama (Recommended for Enterprise)

# .env
EMBEDDING_PROVIDER=ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=nomic-embed-text
CHROMA_HOST=localhost
CHROMA_PORT=8000

Using OpenAI

# .env
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=your-api-key
OPENAI_MODEL=text-embedding-3-small

Claude Desktop Integration

To use this MCP server with Claude Desktop, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "enterprise-code-search": {
      "command": "node",
      "args": ["/path/to/semantic-context-mcp/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_MODEL": "nomic-embed-text",
        "CHROMA_HOST": "localhost",
        "CHROMA_PORT": "8000",
        "COMPANY_NAME": "YourCompany"
      }
    }
  }
}

Available Tools

Example Queries

Functional searches

• "Where is the authentication logic?"
• "Functions that handle database operations"
• "Environment variable configuration"
• "Unit tests for the API"

Code analysis

• "What design patterns are used?"
• "Most complex functions in the project"
• "Error handling in the code"

Technology-specific search

• "Code using React hooks"
• "PostgreSQL queries"
• "Docker configuration"

Advanced Configuration

Recommended Ollama Models

# For code embeddings
ollama pull nomic-embed-text    # Best for code (384 dims)
ollama pull all-minilm         # Lightweight alternative (384 dims)
ollama pull mxbai-embed-large  # Higher precision (1024 dims)

File Patterns

The server supports extensive file type recognition including:

• Programming Languages: Python, JavaScript/TypeScript, Java, C/C++, Go, Rust, PHP, Ruby, Swift, Kotlin, Scala, and more
• Web Technologies: HTML, CSS, SCSS, Vue, Svelte
• Configuration: JSON, YAML, TOML, Docker, Terraform
• Documentation: Markdown, reStructuredText, AsciiDoc
• Database: SQL files

Performance Tuning

# Maximum chunk size (characters)
MAX_CHUNK_SIZE=1500

# Maximum file size (KB)
MAX_FILE_SIZE=500

# Batch size for indexing
BATCH_SIZE=100

Enterprise Deployment

Option 1: Dedicated Server

# On enterprise server
docker-compose up -d

Option 2: Network Deployment

# Configure for network access
CHROMA_HOST=192.168.1.100
OLLAMA_HOST=http://192.168.1.100:11434

Security Considerations

Key Benefits

1. Private Data: Ollama keeps everything local.
2. No External APIs: When using Ollama, no data leaves your network.
3. Self-hosted: Full control over your code and embeddings.
4. Isolated Environment: Docker containers provide isolation.

Security Best Practices

# Restrict ChromaDB access
CHROMA_SERVER_HOST=127.0.0.1  # Localhost only

# Use HTTPS for production
OLLAMA_HOST=https://ollama.company.com

Monitoring & Troubleshooting

Useful Logs

# View indexing logs
docker-compose logs -f enterprise-mcp-server

# ChromaDB performance
docker-compose logs -f chromadb

# Monitor Ollama
curl http://localhost:11434/api/tags

Common Issues

Ollama not responding:

curl http://localhost:11434/api/tags
# If it fails: docker-compose restart ollama

ChromaDB slow:

# Check disk space
docker system df
# Clean if necessary
docker system prune

Poor embedding quality:

• Try different model: all-minilm vs nomic-embed-text
• Adjust chunk size
• Verify source file quality

Collaborative Workflow

Typical Enterprise Workflow

1. DevOps indexes main projects.
2. Developers search code using Claude.
3. Automatic updates via CI/CD.
4. Code analysis for code reviews.

Best Practices

• Index after important merges.
• Use descriptive project names.
• Maintain project-specific search filters.
• Document naming conventions

Development

Project Structure

src/
├── index.ts          # Main MCP server
└── http-server.ts    # HTTP server variant

scripts/              # Setup and utility scripts
docker-compose.yml    # Service orchestration
package.json         # Dependencies and scripts

Available Scripts

npm run build        # Compile TypeScript
npm run dev          # Development mode
npm run start        # Production mode
npm run clean        # Clean build directory

🔧 Technical Details

The MCP server implements the standard Model Context Protocol with these specific tools:

• index_local_project: Index local directories with configurable file patterns.
• search_codebase: Semantic search with project filtering and similarity scoring.
• list_indexed_projects: Enumerate all indexed projects with metadata.
• get_embedding_provider_info: Get current provider status and configuration. Each tool includes detailed JSON schema with examples and validation.

🤖 Recommended AI Models

For embeddings (Ollama)

• nomic-embed-text: Optimized for code.
• all-minilm: Balanced, fast.
• mxbai-embed-large: High precision.

For embeddings (OpenAI)

• text-embedding-3-small: Cost-effective.
• text-embedding-3-large: Higher precision.

🐳 Docker Support

The project includes a complete Docker setup:

• ChromaDB: Vector database for embeddings.
• Ollama: Local embedding generation.
• PostgreSQL: Optional metadata storage. All services are orchestrated with Docker Compose for easy deployment.

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

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

1. Fork the project.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

📞 Support & Issues

• 📧 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• ☕ Support: Buy Me a Coffee