Context Optimizer MCP Server

🚀 Context Optimizer MCP Server

A Model Context Protocol (MCP) server providing context optimization tools for AI coding assistants to enhance efficiency and focus.

🚀 Quick Start

Installation

1. Install globally:

npm install -g context-optimizer-mcp-server

Configuration

2. Set environment variables (see docs/guides/usage.md for OS-specific instructions):

export CONTEXT_OPT_LLM_PROVIDER="gemini"
export CONTEXT_OPT_GEMINI_KEY="your-gemini-api-key"
export CONTEXT_OPT_EXA_KEY="your-exa-api-key"
export CONTEXT_OPT_ALLOWED_PATHS="/path/to/your/projects"

Integration

3. Add to your MCP client configuration:

like "mcpServers" in claude_desktop_config.json (Claude Desktop) or "servers" in mcp.json (VS Code).

"context-optimizer": {
  "command": "context-optimizer-mcp"
}

For complete setup instructions including OS-specific environment variable configuration and AI assistant setup, see docs/guides/usage.md.

✨ Features

• 🔍 File Analysis Tool (askAboutFile) - Extract specific information from files without loading entire contents
• 🖥️ Terminal Execution Tool (runAndExtract) - Execute commands and extract relevant information using LLM analysis
• ❓ Follow-up Questions Tool (askFollowUp) - Continue conversations about previous terminal executions
• 🔬 Research Tools (researchTopic, deepResearch) - Conduct web research using Exa.ai's API
• 🔒 Security Controls - Path validation, command filtering, and session management
• 🔧 Multi-LLM Support - Works with Google Gemini, Claude (Anthropic), and OpenAI
• ⚙️ Environment Variable Configuration - API key management through system environment variables
• 🏗️ Simple Configuration - Environment variables only, no config files to manage
• 🧪 Comprehensive Testing - Unit tests, integration tests, and security validation

🎯 The Problem It Solves

Have you ever experienced these issues with your AI coding assistant (like Copilot, Claude Code, or Cursor)?

• 🔄 Your assistant keeps compacting/summarizing conversations and losing a bit of the context in the process.
• 🖥️ Terminal outputs flood the context with hundreds of lines when the assistant only needs key information.
• 📄 Large files overwhelm the context when the assistant just needs to check one specific thing.
• ⚠️ "Context limit reached" messages interrupting your workflow.
• 🧠 Your assistant "forgets" earlier parts of your conversation due to context overflow.
• 😫 The reasoning quality drops when you have a longer conversation.

The Root Cause: When your assistant:

• Reads long logs during builds, tests, lints, etc. after executing a terminal command.
• Reads a large file (or multiple) in full just to answer a question when it doesn't need the whole code.
• Reads multiple web pages from the web to search a topic to learn how to do something.
• Or just during a long conversation.

The assistant will either:

• Start compacting, summarizing or truncating the conversation history.
• Drop the quality of reasoning.
• Lose track of earlier context and decisions.
• Become less helpful as it loses focus.

The Solution:

This server provides any MCP-compatible assistant with specialized tools that extract only the specific information you need, keeping your chat context clean and focused on productive problem-solving rather than data management.

💻 Usage Examples

Basic Usage

The following steps show how to install and configure the server:

# Install globally
npm install -g context-optimizer-mcp-server

# Set environment variables
export CONTEXT_OPT_LLM_PROVIDER="gemini"
export CONTEXT_OPT_GEMINI_KEY="your-gemini-api-key"
export CONTEXT_OPT_EXA_KEY="your-exa-api-key"
export CONTEXT_OPT_ALLOWED_PATHS="/path/to/your/projects"

# Add to MCP client configuration
{
  "context-optimizer": {
    "command": "context-optimizer-mcp"
  }
}

Advanced Usage

Here's how to run tests with API keys for full integration testing:

# Set environment variables
export CONTEXT_OPT_LLM_PROVIDER="gemini"
export CONTEXT_OPT_GEMINI_KEY="your-gemini-key"
export CONTEXT_OPT_EXA_KEY="your-exa-key"

# Run all tests including LLM integration
npm test

📚 Documentation

All documentation is organized under the docs/ directory:

Quick Links

• Get Started: See docs/guides/usage.md for complete setup instructions
• Tools Reference: Check docs/tools.md for detailed tool documentation
• Troubleshooting: Check docs/guides/troubleshooting.md for common issues
• VS Code Setup: Follow docs/guides/vs-code-setup.md for VS Code configuration

🧪 Testing

# Run all tests (skips LLM integration tests without API keys)
npm test

# Run tests with API keys for full integration testing
# Set environment variables first:
export CONTEXT_OPT_LLM_PROVIDER="gemini"
export CONTEXT_OPT_GEMINI_KEY="your-gemini-key"
export CONTEXT_OPT_EXA_KEY="your-exa-key"
npm test  # Now runs all tests including LLM integration

# Run in watch mode
npm run test:watch

For detailed testing setup, see docs/reference/testing.md.

👥 Contributing

Contributions are welcome! Please read docs/reference/contributing.md for guidelines on development workflow, coding standards, testing, and submitting pull requests.

🌐 Community

• Code of Conduct: See docs/reference/code-of-conduct.md
• Security Reports: Follow docs/reference/security.md for responsible disclosure
• Issues: Use GitHub Issues for bugs & feature requests
• Pull Requests: Ensure tests pass and docs are updated
• Discussions: (If enabled) Use for open-ended questions/ideas

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

• VS Code Copilot Context Optimizer – Original VS Code extension (companion project)