scout-mcp 0.2.3

MCP server for Scout - exposes Scout query capabilities to other agents

Ceregrep MCP Server

MCP (Model Context Protocol) server that exposes ceregrep query capabilities to other agents.

What is This?

This MCP server allows any MCP-compatible agent (like Claude Desktop) to use ceregrep as a tool for querying and analyzing codebases. Instead of the agent manually using bash and grep, it can ask ceregrep (which has its own LLM-powered analysis) to find context.

Features

• ceregrep_query: Query ceregrep to find context in codebases
  • Natural language queries (e.g., "Find all async functions", "Explain the auth flow")
  • Automatic code exploration using ceregrep's bash + grep tools
  • LLM-powered analysis and context gathering

Prerequisites

1. Ceregrep CLI installed globally:

   npm install -g ceregrep
   

2. Python ≥ 3.10 (for pip installation) or uvx (for no-install usage)

Installation

Option 1: Using uvx (Recommended - No Installation Required)

# No installation needed! Just use uvx to run it
uvx ceregrep-mcp

Option 2: Install via pip

pip install ceregrep-mcp

Option 3: Install from source (Development)

cd mcp-server
pip install -e .

Usage

Using with uvx (Recommended)

The easiest way to use ceregrep-mcp is with uvx, which runs the package without installation:

uvx ceregrep-mcp

Add to Claude Desktop

Method 1: Using Claude MCP CLI (Easiest)

claude mcp add ceregrep uvx ceregrep-mcp

This automatically adds ceregrep-mcp to your Claude configuration.

Method 2: Manual Configuration

Edit your Claude Desktop MCP configuration file:

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

Add this configuration:

{
  "mcpServers": {
    "ceregrep": {
      "command": "uvx",
      "args": ["ceregrep-mcp"]
    }
  }
}

If you installed via pip:

{
  "mcpServers": {
    "ceregrep": {
      "command": "ceregrep-mcp"
    }
  }
}

Add to Other MCP Clients

For any MCP-compatible client, add to your mcp.json or equivalent config file:

{
  "mcpServers": {
    "ceregrep": {
      "command": "uvx",
      "args": ["ceregrep-mcp"],
      "env": {}
    }
  }
}

Add to Ceregrep Itself (Recursive Pattern)

You can even use ceregrep's own MCP client to connect to this server! Add to .ceregrep.json or ~/.ceregrep.json:

{
  "mcpServers": {
    "ceregrep-context": {
      "type": "stdio",
      "command": "uvx",
      "args": ["ceregrep-mcp"]
    }
  }
}

Now ceregrep can delegate context-finding to another instance of itself!

Available Tools

ceregrep_query

Query ceregrep to find context in a codebase.

Parameters:

• query (required): Natural language query
• cwd (optional): Working directory to run ceregrep in
• model (optional): LLM model to use
• verbose (optional): Enable verbose output

Example queries:

• "Find all async functions in this codebase"
• "Explain how the authentication system works"
• "Show me all API endpoints"
• "Find files that handle database connections"
• "Analyze the project architecture"

Agent Tools (7 Specialized Agents)

All ceregrep agents are automatically exposed as MCP tools! External systems like Claude Code can invoke specialized agents directly.

Available agents:

1. agent_debug_agent - Debugging expert

   • Analyzes error messages and stack traces
   • Identifies root causes of bugs
   • Suggests fixes with explanations

2. agent_context_agent - Context discovery specialist

   • Explores codebases systematically
   • Maps architecture and code flows
   • Provides comprehensive context

3. agent_postgres_agent - PostgreSQL specialist

   • Database schema analysis
   • Query optimization
   • SQL best practices

4. agent_review_agent - Code review expert

   • Reviews code for quality and best practices
   • Identifies security vulnerabilities
   • Suggests improvements

5. agent_test_agent - Test writing specialist

   • Writes comprehensive unit/integration tests
   • Identifies test coverage gaps
   • Follows testing best practices

6. agent_docs_agent - Documentation expert

   • Generates API documentation
   • Writes README files and guides
   • Creates clear, comprehensive docs

7. agent_orchestrator_agent - Meta-agent coordinator

   • Coordinates multiple specialized agents
   • Breaks down complex problems
   • Synthesizes responses from agents

Parameters (all agents):

• prompt (required): The prompt/query to send to the agent
• cwd (optional): Working directory to run in
• model (optional): LLM model to use
• verbose (optional): Enable verbose output

Example usage:

• agent_debug_agent: "Why is my authentication failing with a 401 error?"
• agent_context_agent: "Explain the payment processing system architecture"
• agent_review_agent: "Review the authentication middleware for security issues"

Example: Using Agents from Claude Code

Once you've added ceregrep-mcp to Claude Code, you can ask Claude to use specialized agents:

User: "Use the debug-agent to investigate why login is returning 401 errors"

Claude Code: (Sees agent_debug_agent as available tool, invokes it)

The debug agent will:

1. Explore your authentication code
2. Check error handling patterns
3. Analyze JWT validation logic
4. Provide specific debugging guidance

Response format:

## Debug Agent Response

**Prompt:** Investigate why login is returning 401 errors

I've analyzed your authentication system. Here's what I found:

1. JWT Token Validation (src/auth/middleware.ts:45)
   - The token expiration check is failing
   - Issue: Clock skew between server and client

2. Suggested Fix:
   - Add a 30-second leeway to token validation
   - Update JWT_VERIFY_OPTIONS to include clockTolerance

[... detailed debugging context ...]

How It Works

1. Agent sends a natural language query to ceregrep_query tool
2. MCP server invokes the ceregrep CLI with the query
3. Ceregrep uses its own LLM + bash + grep tools to explore the codebase
4. Results are returned to the requesting agent

This creates a recursive agent pattern where agents can delegate complex context-finding to specialized sub-agents.

Configuration

The MCP server uses the ceregrep CLI, which reads configuration from:

• .ceregrep.json in the working directory
• ~/.config/ceregrep/config.json (global config)
• Environment variables (ANTHROPIC_API_KEY, CEREBRAS_API_KEY)

Development

Project Structure

mcp-server/
├── mcp_server.py           # Main MCP server
├── tool_discovery.py       # Auto-discovery system
├── tools/
│   ├── base_tool.py        # Base tool class
│   └── ceregrep_query_tool.py  # Ceregrep query tool
├── pyproject.toml          # Dependencies
└── README.md               # This file

Adding New Tools

1. Create a new file in tools/
2. Inherit from BaseTool
3. Implement name, description, input_schema, and execute()
4. Restart server - tool is auto-discovered!

Agent Discovery and Caching

The MCP server automatically discovers agents by running ceregrep agent list --json. To optimize performance:

• Agent list is cached for 5 minutes - New agents will be visible within 5 minutes without restarting the MCP server
• Cache refreshes automatically - After 5 minutes, the agent list is refreshed on the next tool list request
• Manual refresh - Restart the MCP server to immediately refresh the agent list

This means you can:

1. Create a new agent with ceregrep agent init or ceregrep agent import
2. Use it in Claude Code within 5 minutes (or restart the MCP server for immediate availability)

Troubleshooting

"ceregrep command not found"

Run npm link in the ceregrep-client directory to install the CLI globally.

MCP connection errors

Ensure Python ≥ 3.10 and uv are installed:

python --version  # Should be ≥ 3.10
uv --version      # Should be installed

Query failures

Check ceregrep configuration:

ceregrep config  # View current config

Ensure API keys are set:

• ANTHROPIC_API_KEY for Claude
• CEREBRAS_API_KEY for Cerebras

License

AGPL-3.0-or-later