context-please

Your entire codebase as Claude's context

Note: This is a fork of claude-context by Zilliz, maintained by PleaseAI with additional features and improvements.

Extensions Status: Chrome and VSCode extensions are currently TBD (To Be Determined) and not yet available in this fork.

Context Please is an MCP plugin that adds semantic code search to Claude Code and other AI coding agents, giving them deep context from your entire codebase.

🧠 Your Entire Codebase as Context: Claude Context uses semantic search to find all relevant code from millions of lines. No multi-round discovery needed. It brings results straight into the Claude's context.

💰 Cost-Effective for Large Codebases: Instead of loading entire directories into Claude for every request, which can be very expensive, Claude Context efficiently stores your codebase in a vector database and only uses related code in context to keep your costs manageable.

🚀 Demo

Model Context Protocol (MCP) allows you to integrate Claude Context with your favorite AI coding assistants, e.g. Claude Code.

Quick Start

Prerequisites

🚀 New: Zero-Config Local Mode with FAISS

You can now use Context Please with no external database required! Simply provide an OpenAI API key, and FAISS will handle local storage automatically. Perfect for getting started quickly or working with small-to-medium codebases.

For production deployments or large codebases, consider using Zilliz Cloud or Qdrant:

Configure MCP for Claude Code

System Requirements:

• Node.js >= 20.0.0 and < 24.0.0

Claude Context is not compatible with Node.js 24.0.0, you need downgrade it first if your node version is greater or equal to 24.

Configuration

Option 1: Local Mode with FAISS (Recommended for Getting Started)

The simplest way to get started - no external database required:

claude mcp add context-please \
  -e OPENAI_API_KEY=sk-your-openai-api-key \
  -- npx @pleaseai/context-please-mcp@latest

Option 2: Cloud Mode with Zilliz (For Production/Large Codebases)

For larger codebases or production deployments:

claude mcp add context-please \
  -e OPENAI_API_KEY=sk-your-openai-api-key \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -- npx @pleaseai/context-please-mcp@latest

See the Claude Code MCP documentation for more details about MCP server management.

Other MCP Client Configurations

# IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
[mcp_servers.context-please]
command = "npx"
args = ["@pleaseai/context-please-mcp@latest"]
env = { "OPENAI_API_KEY" = "your-openai-api-key", "MILVUS_TOKEN" = "your-zilliz-cloud-api-key" }
# Optional: override the default 10s startup timeout
startup_timeout_ms = 20000

{
  "mcpServers": {
    "context-please": {
      "command": "npx",
      "args": ["@pleaseai/context-please-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["@pleaseai/context-please-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "context-please": {
      "command": "npx",
      "args": ["-y", "@pleaseai/context-please-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "context-please": {
      "command": "npx",
      "args": ["-y", "@pleaseai/context-please-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["@pleaseai/context-please-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "context-please": {
      "command": "npx",
      "args": ["-y", "@pleaseai/context-please-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "context-please": {
      "command": "npx",
      "args": ["-y", "@pleaseai/context-please-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["@pleaseai/context-please-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

"augment.advanced": {
  "mcpServers": [
    {
      "name": "context-please",
      "command": "npx",
      "args": ["-y", "@pleaseai/context-please-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  ]
}

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["@pleaseai/context-please-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

{
    "command": "npx",
    "args": ["@pleaseai/context-please-mcp@latest"],
    "env": {
      "OPENAI_API_KEY": "your-openai-api-key",
      "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
      "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
    }
}

npx @pleaseai/context-please-mcp@latest

Usage in Your Codebase

1. Open Claude Code

   cd your-project-directory
   claude
   

2. Index your codebase:

   Index this codebase
   

3. Check indexing status:

   Check the indexing status
   

4. Start searching:

   Find functions that handle user authentication
   

🎉 That's it! You now have semantic code search in Claude Code.

Environment Variables Configuration

For more detailed MCP environment variable configuration, see our Environment Variables Guide.

Using FAISS for Local-Only Deployments

Context Please now supports FAISS as a zero-configuration, local-only vector database option! This is perfect for:

• 🚀 Quick Start: No external database setup required
• 💻 Local Development: All data stays on your machine
• 💰 Zero Cost: No cloud services or infrastructure costs
• 📦 Small-to-Medium Codebases: Ideal for personal projects and teams

Quick Start with FAISS

Simply omit the Milvus/Qdrant configuration, and Context Please will automatically use FAISS:

claude mcp add context-please \
  -e OPENAI_API_KEY=sk-your-openai-api-key \
  -- npx @pleaseai/context-please-mcp@latest

That's it! Your code will be indexed to ~/.context/faiss-indexes/ automatically.

Advanced FAISS Configuration

You can customize the storage directory:

claude mcp add context-please \
  -e OPENAI_API_KEY=sk-your-openai-api-key \
  -e FAISS_STORAGE_DIR=/path/to/your/indexes \
  -- npx @pleaseai/context-please-mcp@latest

Or explicitly specify FAISS as the vector database:

{
  "mcpServers": {
    "context-please": {
      "command": "npx",
      "args": ["@pleaseai/context-please-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "VECTOR_DB_TYPE": "faiss-local",
        "FAISS_STORAGE_DIR": "~/.context/faiss-indexes"
      }
    }
  }
}

FAISS Features

• ✅ Hybrid Search: Combines dense (semantic) + sparse (BM25) vectors
• ✅ File-based Persistence: Indexes saved as .index files
• ✅ Auto-selection: Defaults to FAISS when no external DB configured
• ✅ Same Interface: Compatible with all existing tools and APIs

Limitations

• ⚠️ Memory: Entire index loads into RAM (suitable for ~100K files)
• ⚠️ Concurrency: Single-process file access
• ⚠️ Scalability: For larger codebases, consider Milvus or Qdrant

For production deployments or large codebases (>100K files), we recommend using Milvus or Qdrant.

Using Different Embedding Models

To configure custom embedding models (e.g., text-embedding-3-large for OpenAI, voyage-code-3 for VoyageAI), see the MCP Configuration Examples for detailed setup instructions for each provider.

File Inclusion & Exclusion Rules

For detailed explanation of file inclusion and exclusion rules, and how to customize them, see our File Inclusion & Exclusion Rules.

Available Tools

1. index_codebase

Index a codebase directory for hybrid search (BM25 + dense vector).

2. search_code

Search the indexed codebase using natural language queries with hybrid search (BM25 + dense vector).

3. clear_index

Clear the search index for a specific codebase.

4. get_indexing_status

Get the current indexing status of a codebase. Shows progress percentage for actively indexing codebases and completion status for indexed codebases.

📊 Evaluation

Our controlled evaluation demonstrates that Claude Context MCP achieves ~40% token reduction under the condition of equivalent retrieval quality. This translates to significant cost and time savings in production environments. This also means that, under the constraint of limited token context length, using Claude Context yields better retrieval and answer results.

For detailed evaluation methodology and results, see the evaluation directory.

🏗️ Architecture

🔧 Implementation Details

• 🔍 Hybrid Code Search: Ask questions like "find functions that handle user authentication" and get relevant, context-rich code instantly using advanced hybrid search (BM25 + dense vector).
• 🧠 Context-Aware: Discover large codebase, understand how different parts of your codebase relate, even across millions of lines of code.
• ⚡ Incremental Indexing: Efficiently re-index only changed files using Merkle trees.
• 🧩 Intelligent Code Chunking: Analyze code in Abstract Syntax Trees (AST) for chunking.
• 🗄️ Scalable: Integrates with vector databases (Milvus, Zilliz Cloud, Qdrant) for scalable vector search, no matter how large your codebase is.
• 🛠️ Customizable: Configure file extensions, ignore patterns, and embedding models.

Core Components

Context Please is a monorepo containing main packages:

• @pleaseai/context-please-core: Core indexing engine with embedding and vector database integration
• @pleaseai/context-please-mcp: Model Context Protocol server for AI agent integration
• VSCode Extension: TBD (To Be Determined)
• Chrome Extension: TBD (To Be Determined)

Supported Technologies

• Embedding Providers: OpenAI, VoyageAI, Ollama, Gemini
• Vector Databases: Milvus, Zilliz Cloud(fully managed vector database as a service), Qdrant
• Code Splitters: AST-based splitter (with automatic fallback), LangChain character-based splitter
• Languages: TypeScript, JavaScript, Python, Java, C++, C#, Go, Rust, PHP, Ruby, Swift, Kotlin, Scala, Markdown
• Development Tools: VSCode, Model Context Protocol

📦 Other Ways to Use Claude Context

While MCP is the recommended way to use Claude Context with AI assistants, you can also use it directly or through the VSCode extension.

Build Applications with Core Package

The @pleaseai/context-please-core package provides the fundamental functionality for code indexing and semantic search.

import { Context, MilvusVectorDatabase, OpenAIEmbedding } from '@pleaseai/context-please-core';

// Initialize embedding provider
const embedding = new OpenAIEmbedding({
    apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',
    model: 'text-embedding-3-small'
});

// Initialize vector database
const vectorDatabase = new MilvusVectorDatabase({
    address: process.env.MILVUS_ADDRESS || 'your-zilliz-cloud-public-endpoint',
    token: process.env.MILVUS_TOKEN || 'your-zilliz-cloud-api-key'
});

// Create context instance
const context = new Context({
    embedding,
    vectorDatabase
});

// Index your codebase with progress tracking
const stats = await context.indexCodebase('./your-project', (progress) => {
    console.log(`${progress.phase} - ${progress.percentage}%`);
});
console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);

// Perform semantic search
const results = await context.semanticSearch('./your-project', 'vector database operations', 5);
results.forEach(result => {
    console.log(`File: ${result.relativePath}:${result.startLine}-${result.endLine}`);
    console.log(`Score: ${(result.score * 100).toFixed(2)}%`);
    console.log(`Content: ${result.content.substring(0, 100)}...`);
});

VSCode Extension

Note: VSCode extension is currently TBD (To Be Determined) and not yet available in this fork. Please use the original claude-context VSCode extension for now.

🛠️ Development

Setup Development Environment

Prerequisites

• Node.js 20.x or 22.x
• pnpm (recommended package manager)

Cross-Platform Setup

# Clone repository
git clone https://github.com/pleaseai/context-please.git
cd context-please

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Start development mode
pnpm dev

Windows-Specific Setup

On Windows, ensure you have:

• Git for Windows with proper line ending configuration
• Node.js installed via the official installer or package manager
• pnpm installed globally: npm install -g pnpm

# Windows PowerShell/Command Prompt
git clone https://github.com/pleaseai/context-please.git
cd context-please

# Configure git line endings (recommended)
git config core.autocrlf false

# Install dependencies
pnpm install

# Build all packages (uses cross-platform scripts)
pnpm build

# Start development mode
pnpm dev

Building

# Build all packages (cross-platform)
pnpm build

# Build specific package
pnpm build:core
pnpm build:vscode
pnpm build:mcp

# Performance benchmarking
pnpm benchmark

Windows Build Notes

• All build scripts are cross-platform compatible using rimraf
• Build caching is enabled for faster subsequent builds
• Use PowerShell or Command Prompt - both work equally well

Testing

Context Please includes comprehensive integration tests for both the core indexing engine and MCP server.

# Run all tests (unit + integration)
pnpm test

# Run only integration tests (123 tests)
pnpm test:integration

# Run tests for specific package
cd packages/core && pnpm test          # All core tests
cd packages/core && pnpm test:integration  # Core integration tests only
cd packages/mcp && pnpm test:integration   # MCP integration tests only

# Run specific test file
pnpm test packages/core/test/integration/indexing-workflow.integration.test.ts

Test Coverage:

• Core integration tests: 93 tests (100% passing)
  • Indexing workflow (15 tests): Basic indexing operations
  • Search workflow (18 tests): Semantic search and ranking
  • Lifecycle (17 tests): Collection management
  • File synchronization (24 tests): Merkle DAG-based change detection
  • Incremental reindex (19 tests): File add/modify/delete operations
• MCP integration tests: 30 tests (100% passing)
  • Tool handlers: index_codebase, search_code, clear_index, get_indexing_status

For detailed testing guidelines, see docs/develop/TESTING.md.

Running Examples

# Development with file watching
cd examples/basic-usage
pnpm dev

📖 Examples

Check the /examples directory for complete usage examples:

• Basic Usage: Simple indexing and search example

❓ FAQ

Common Questions:

• What files does Claude Context decide to embed?
• Can I use a fully local deployment setup?
• Does it support multiple projects / codebases?
• How does Claude Context compare to other coding tools?

❓ For detailed answers and more troubleshooting tips, see our FAQ Guide.

🔧 Encountering issues? Visit our Troubleshooting Guide for step-by-step solutions.

📚 Need more help? Check out our complete documentation for detailed guides and troubleshooting tips.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

Package-specific contributing guides:

• Core Package Contributing
• MCP Server Contributing
• VSCode Extension Contributing

🗺️ Roadmap

• AST-based code analysis for improved understanding
• Support for additional embedding providers
• Agent-based interactive search mode
• Enhanced code chunking strategies
• Search result ranking optimization
• Robust Chrome Extension

📄 License

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

🔗 Links

• GitHub Repository
• Original Project (claude-context)
• npm - Core Package
• npm - MCP Server
• Milvus Documentation
• Zilliz Cloud
• Qdrant Documentation