Claude Code MCP Integration Setup

This guide explains how to connect Claude Code to your WDG AI Development Environment's MCP server for intelligent code search and assistance.

Prerequisites

1. WDG Services Running

   # Start all services including MCP server
   wdg start
   
   # Verify MCP is running (should show port 8765)
   wdg status

2. Code Indexed

   # Index the Wikit framework
   wdg index
   
   # Index your project
   wdg index my-project
   
   # Verify collections exist
   wdg collections list

Configure Claude Code

Step 1: Open Claude Code Settings

1. Open Claude Code
2. Go to Settings (gear icon)
3. Navigate to "MCP Servers" or "Model Context Protocol"

Step 2: Add WDG MCP Server

Add this configuration to your Claude Code MCP settings:

{
  "mcpServers": {
    "wdg-local": {
      "command": "python3",
      "args": [
        "${WDG_HOME}/mcp-server/server.py"
      ],
      "env": {
        "QDRANT_HOST": "localhost",
        "QDRANT_PORT": "6333",
        "MCP_PORT": "8765"
      }
    }
  }
}

Alternative: Using Network Connection

If the above doesn't work, try connecting directly to the running server:

{
  "mcpServers": {
    "wdg-local": {
      "uri": "http://localhost:8765",
      "transport": "http"
    }
  }
}

Step 3: Restart Claude Code

After adding the configuration, restart Claude Code to load the MCP server connection.

Available MCP Tools

Once connected, Claude Code can use these tools:

1. search_codebase

Search across your indexed code with text matching.

Example prompts:

• "Find all user authentication functions"
• "Search for database queries in my-project"
• "Show me all WordPress hooks"

2. list_collections

See all indexed projects and the framework.

Example: "What projects are indexed?"

3. search_functions

Find specific functions by name.

Example: "Find the get_user_data function"

4. search_wordpress_hooks

Search for WordPress actions and filters.

Example: "Show me all init hooks"

5. search_classes

Find PHP or JavaScript classes.

Example: "Find the UserController class"

6. search_wikit_blocks

Search for Wikit Gutenberg blocks.

Example: "Show me all hero blocks"

7. get_project_info

Get information about a specific project.

Example: "Tell me about the client-site project"

8. search_recent_changes

See recently indexed code.

Example: "What code was recently indexed?"

Testing the Connection

In Claude Code, try these commands:

1. Test basic connection:

   Use the list_collections tool to show me what's indexed

2. Search the framework:

   Search for WordPress init hooks in the framework

3. Search a project:

   Find all functions in my-project that handle user data

How It Works

%%{init: {'theme':'neutral'}}%%
graph LR
    Claude[Claude Code] --> MCP[MCP Server<br/>localhost:8765]
    MCP --> Qdrant[Qdrant DB<br/>localhost:6333]
    Qdrant --> Collections[Collections<br/>- wdg_framework<br/>- project_my_site<br/>- project_client_site]

1. Claude Code sends search requests to MCP server
2. MCP Server queries Qdrant using metadata filters
3. Qdrant returns matching code from indexed collections
4. Results are formatted and sent back to Claude

Important Notes

No Embeddings in MCP

The MCP server does NOT generate embeddings. It only queries the existing indexed data using:

• Text matching in code content
• Metadata filtering (file types, component types)
• Collection-specific searches

Text-Based Search

Since MCP can't generate embeddings, searches are text-based:

• Exact or partial text matches
• Case-insensitive searching
• Metadata filtering for precision

Indexing Required

Projects must be indexed BEFORE searching:

# Index a project first
wdg index my-project

# Then search it in Claude
"Search for functions in my-project"

Troubleshooting

MCP Server Not Connecting

1. Check if services are running:

   docker ps | grep mcp
   netstat -an | grep 8765

2. Check logs:

   docker logs wdg-mcp

3. Restart MCP:

   wdg stop
   wdg start

No Search Results

1. Verify indexing:

   wdg collections list

2. Re-index if needed:

   wdg index --update
   wdg index my-project

3. Check collection names:

   • Framework: wdg_framework
   • Projects: project_<name> (hyphens become underscores)

Connection Refused

1. Check firewall:

   sudo ufw allow 8765

2. Verify binding: The MCP server binds to 0.0.0.0:8765 by default

3. Try localhost explicitly: Use http://127.0.0.1:8765 instead of localhost

Advanced Configuration

Custom Port

Change MCP port in .env:

MCP_PORT=9000

Then update Claude Code config accordingly.

Authentication (Optional)

Add token authentication in .env:

MCP_AUTH_TOKEN=your-secret-token

Update Claude Code config:

{
  "mcpServers": {
    "wdg-local": {
      "uri": "http://localhost:8765",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

Example Claude Code Session

Once connected, you can have conversations like:

You: "Show me what projects are indexed" Claude: Uses list_collections tool "I can see 2 collections: wdg_framework with 15,000 vectors and project_client_site with 3,000 vectors."

You: "Find all user authentication functions in client-site" Claude: Uses search_functions tool "I found 5 authentication-related functions in client-site..."

You: "Show me how Wikit blocks are registered" Claude: Uses search_wikit_blocks tool "Here are the Wikit block registrations I found..."

MCP Integration Capabilities

1. Context-Aware Assistance: Claude accesses your indexed codebase
2. Project-Specific Search: Query within specific project scopes
3. Framework Knowledge: Semantic search across Wikit patterns
4. Local Processing: All operations run on your machine
5. Privacy: Code remains on local infrastructure

---

Need Help? Check the main documentation or run wdg help