Skip to content

mcp-configuration.md

Latest commit

 

History

History
268 lines (199 loc) · 8.92 KB

mcp-configuration.md

File metadata and controls

268 lines (199 loc) · 8.92 KB
Raw

Configuring MCP

CocoSearch provides an MCP (Model Context Protocol) server for semantic code search integration with LLM clients. Once configured, your AI assistant can search your codebase using natural language, index new projects, and check index health -- all without leaving the conversation.

Prerequisites

Start the infrastructure services:

docker compose --profile ollama up -d

This gives you PostgreSQL (with pgvector) on port 5432 and Ollama (with nomic-embed-text) on port 11434. If using a remote embedding provider (OpenAI, OpenRouter), you only need PostgreSQL: docker compose up -d. The database connection defaults to postgresql://cocosearch:cocosearch@localhost:5432/cocosearch, which matches the Docker credentials -- no environment variables needed.

Available MCP Tools

  • index_codebase -- index a directory for semantic search
  • search_code -- search indexed code with natural language queries (supports cross-index search via index_names parameter; auto-expands to linkedIndexes from cocosearch.yaml when configured)
  • analyze_query -- pipeline diagnostics for search queries
  • list_indexes -- list all available indexes
  • index_stats -- get statistics and parse health for an index
  • clear_index -- remove an index from the database
  • get_file_dependencies -- forward dependency query (what does a file depend on?)
  • get_file_impact -- reverse impact query (what depends on this file?)
  • get_batch_dependencies -- batch forward dependency query for multiple files
  • get_batch_impact -- batch reverse impact query for multiple files

Single Registration (Recommended)

Register CocoSearch once for all your projects using Claude Code:

claude mcp add --scope user cocosearch -- \
  uvx --from cocosearch cocosearch mcp --project-from-cwd

What these flags do:

  • --scope user makes the registration available in all your projects, not just the current one
  • --project-from-cwd tells CocoSearch to detect the project from whichever directory you are working in

Claude Code supports MCP Roots capability, so project detection is fully automatic -- CocoSearch receives the workspace root directly from the client.

To verify:

claude mcp list

Claude Code Plugin (Alternative)

CocoSearch is also available as a Claude Code plugin, which provides the same MCP tools plus workflow skills:

claude plugin marketplace add VioletCranberry/coco-search
claude plugin install cocosearch@cocosearch

Or use the interactive setup:

uv run cocosearch init
# Follow the prompts to install the Claude Code plugin

The plugin is installed globally and available in all your projects. It is managed by Claude Code's plugin system -- installed plugins are tracked in ~/.claude/plugins/installed_plugins.json.

Claude Desktop

Claude Desktop does not support MCP Roots, so it relies on --project-from-cwd for project detection.

Config file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add CocoSearch to your config:

{
  "mcpServers": {
    "cocosearch": {
      "command": "uvx",
      "args": [
        "--from",
        "cocosearch",
        "cocosearch",
        "mcp",
        "--project-from-cwd"
      ]
    }
  }
}

After saving, restart Claude Desktop. You should see the hammer icon in the chat input area with CocoSearch tools listed.

OpenCode

Config file locations:

  • Global: ~/.config/opencode/opencode.json
  • Project: opencode.json in project root
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cocosearch": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "cocosearch",
        "cocosearch",
        "mcp",
        "--project-from-cwd"
      ],
      "enabled": true
    }
  }
}

OpenCode config differs from Claude configs: it uses "type": "local", command is an array (not separate command/args), and it requires an explicit "enabled": true.

Docker (SSE Transport)

When running CocoSearch as a Docker container (docker compose --profile app up), the MCP server uses SSE transport on port 3000. Connect your AI assistant directly to the container URL instead of spawning a local process.

Claude Code:

claude mcp add --scope user cocosearch --url http://localhost:3000/sse

Claude Desktop:

{
  "mcpServers": {
    "cocosearch": {
      "url": "http://localhost:3000/sse"
    }
  }
}

OpenCode:

{
  "mcp": {
    "cocosearch": {
      "type": "remote",
      "url": "http://localhost:3000/sse",
      "enabled": true
    }
  }
}

Replace 3000 with your COCOSEARCH_MCP_PORT if customized. No local Python installation, Ollama, or PostgreSQL needed — the container handles everything.

Custom Database Connection

By default, CocoSearch connects to postgresql://cocosearch:cocosearch@localhost:5432/cocosearch. This matches the Docker Compose credentials, so no configuration is needed for the standard setup.

If you are connecting to a different PostgreSQL instance, set COCOSEARCH_DATABASE_URL:

Claude Code:

claude mcp add --scope user \
  --env COCOSEARCH_DATABASE_URL=postgresql://user:pass@host:5432/dbname \
  cocosearch -- \
  uvx --from cocosearch cocosearch mcp --project-from-cwd

Claude Desktop / OpenCode (JSON config):

Add an "env" block (or "environment" for OpenCode) to your server config:

{
  "env": {
    "COCOSEARCH_DATABASE_URL": "postgresql://user:pass@host:5432/dbname"
  }
}

Remote Embedding Providers

By default, CocoSearch uses Ollama for embeddings. To use a remote provider (OpenAI, OpenRouter) with the MCP server, pass the provider and API key as environment variables during registration.

Claude Code:

claude mcp add --scope user \
  --env COCOSEARCH_EMBEDDING_PROVIDER=openai \
  --env COCOSEARCH_EMBEDDING_API_KEY=sk-... \
  cocosearch -- \
  uvx --from cocosearch cocosearch mcp --project-from-cwd

# Or with a local OpenAI-compatible server (no API key needed):
claude mcp add --scope user \
  --env COCOSEARCH_EMBEDDING_PROVIDER=openai \
  --env COCOSEARCH_EMBEDDING_BASE_URL=http://localhost:8080 \
  --env COCOSEARCH_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5 \
  cocosearch -- \
  uvx --from cocosearch cocosearch mcp --project-from-cwd

Claude Desktop / OpenCode (JSON config):

Add to your server's "env" block (or "environment" for OpenCode):

{
  "env": {
    "COCOSEARCH_EMBEDDING_PROVIDER": "openai",
    "COCOSEARCH_EMBEDDING_API_KEY": "sk-..."
  }
}

For a local OpenAI-compatible server, use COCOSEARCH_EMBEDDING_BASE_URL instead of an API key:

{
  "env": {
    "COCOSEARCH_EMBEDDING_PROVIDER": "openai",
    "COCOSEARCH_EMBEDDING_BASE_URL": "http://localhost:8080",
    "COCOSEARCH_EMBEDDING_MODEL": "BAAI/bge-small-en-v1.5"
  }
}

Supported providers: ollama (default), openai, openrouter. With a remote provider, you do not need Ollama running — only PostgreSQL is required. Use COCOSEARCH_EMBEDDING_BASE_URL (or embedding.baseUrl in config) to point any provider at a custom endpoint.

Query-Rewrite Controller (optional)

The optional query-rewrite controller (disabled by default) can also be configured for the MCP server via environment variables, exactly like the embedding provider:

{
  "env": {
    "COCOSEARCH_CONTROLLER_ENABLED": "true",
    "COCOSEARCH_CONTROLLER_PROVIDER": "openrouter",
    "COCOSEARCH_CONTROLLER_MODEL": "openai/gpt-4o-mini",
    "COCOSEARCH_CONTROLLER_API_KEY": "sk-..."
  }
}

When enabled, search_code rewrites natural-language queries into better search terms before retrieval and emits a query_rewrite header showing original → rewritten. The calling agent can opt out per call with search_code(rewrite_query=False) — recommended when it has already crafted precise terms (exact identifiers, symbol_name/symbol_type filters). The controller falls back to the original query on any error, so search never breaks. The dashboard header status line shows a REWRITE: ON/OFF indicator and a CREDITS: readout (served at /api/credits) of the remaining balance when a remote provider like OpenRouter is in use.

Project Detection

CocoSearch determines which project to search using the following priority chain:

  1. MCP Roots -- if the client supports Roots capability (Claude Code does), the workspace root is received directly from the client. This is the most reliable method.
  2. --project-from-cwd -- detects the project from the current working directory. Used by clients that do not support Roots (Claude Desktop, OpenCode).
  3. Environment variable -- falls back to the configured project path if set.
  4. Current working directory -- unconditional fallback.

For programmatic use via HTTP transport, you can pass the project as a query parameter: ?project=/path/to/project.