MCP API Reference

Complete API documentation for the Model Context Protocol server providing AI-powered code search and project management.

Base URL

http://localhost:8765

Authentication

Currently no authentication required (local development only).

Tools

search_codebase

Semantic search across indexed repositories.

Parameters:

{
  query: string;              // Search query
  project?: string;           // Optional project filter
  file_types?: string[];      // Filter by extensions
  component_type?: string;    // Filter by type (function, class, hook)
  limit?: number;             // Max results (default: 20)
}

Response:

[
  {
    "file_path": "wp-content/themes/custom/functions.php",
    "component_type": "function",
    "component_name": "custom_register_post_types",
    "content": "function custom_register_post_types() {...}",
    "line_start": 45,
    "line_end": 65,
    "language": "php",
    "score": 0.89,
    "project": "my-site"
  }
]

Example:

from mcp import Client

client = Client("http://localhost:8765")

results = client.call_tool("search_codebase", {
    "query": "email validation",
    "file_types": ["php", "js"],
    "limit": 10
})

search_functions

Find functions by name across codebase.

Parameters:

{
  function_name: string;      // Function name (partial match)
  project?: string;           // Optional project filter
  language?: string;          // Filter by language (php, javascript)
}

Response:

[
  {
    "function_name": "validate_email",
    "file_path": "inc/utilities/validators.php",
    "signature": "validate_email($email, $strict = false)",
    "line_start": 12,
    "line_end": 20,
    "docblock": "/**\n * Validate email address\n * @param string $email\n */"
  }
]

search_classes

Find PHP or JavaScript classes.

Parameters:

{
  class_name: string;         // Class name (partial match)
  project?: string;           // Optional project filter
}

Response:

[
  {
    "class_name": "CustomPostType",
    "file_path": "inc/post-types/base.php",
    "namespace": "WDG\\PostTypes",
    "methods": ["__construct", "register", "get_labels"],
    "extends": null,
    "implements": []
  }
]

search_wordpress_hooks

Find WordPress actions and filters.

Parameters:

{
  hook_name: string;          // Hook name (partial match)
  hook_type?: string;         // Type: action, filter, add_action, add_filter
  project?: string;           // Optional project filter
}

Response:

[
  {
    "hook_name": "init",
    "hook_type": "add_action",
    "callback": "custom_init_function",
    "priority": 10,
    "accepted_args": 1,
    "file_path": "functions.php",
    "line_number": 45
  }
]

search_wikit_blocks

Search Wikit Gutenberg blocks.

Parameters:

{
  block_name?: string;        // Optional block name filter
}

Response:

[
  {
    "name": "wdg/hero",
    "title": "Hero Section",
    "category": "wdg-layout",
    "description": "Full-width hero with background image/video",
    "keywords": ["hero", "banner", "header"],
    "attributes": {
      "backgroundType": {"type": "string", "default": "image"},
      "overlayOpacity": {"type": "number", "default": 0.5}
    },
    "example": {
      "attributes": {...}
    }
  }
]

get_project_info

Get project details and indexing status.

Parameters:

{
  project_name: string;       // Project name
}

Response:

{
  "name": "my-site",
  "status": "running",
  "php_version": "8.2",
  "url": "https://my-site.localhost:8443",
  "database": {
    "name": "wp_my_site",
    "size": "45.2 MB"
  },
  "collection": "project_my_site",
  "vectors": 1450,
  "last_indexed": "2024-10-14T10:30:00Z",
  "repositories": [
    {
      "name": "my-site",
      "branch": "main",
      "last_commit": "abc123",
      "commit_date": "2024-10-14T09:00:00Z"
    }
  ]
}

list_collections

List all vector database collections.

Parameters: None

Response:

{
  "collections": [
    {
      "name": "wdg_framework",
      "vectors_count": 15234,
      "indexed_files": 5000,
      "last_updated": "2024-10-14T09:15:00Z"
    },
    {
      "name": "project_my_site",
      "vectors_count": 1450,
      "indexed_files": 500,
      "last_updated": "2024-10-14T10:30:00Z"
    }
  ],
  "total_vectors": 16684,
  "total_size": "52.9 MB"
}

search_recent_changes

Get recently indexed code.

Parameters:

{
  project?: string;           // Optional project filter
  limit?: number;             // Max results (default: 10)
}

Response:

[
  {
    "file_path": "inc/utilities/helpers.php",
    "component_name": "format_phone_number",
    "component_type": "function",
    "indexed_at": "2024-10-14T10:30:00Z",
    "commit_hash": "abc123",
    "author": "John Doe"
  }
]

wordpress_docs

Search WordPress core documentation.

Parameters:

{
  query: string;              // Search query
  type?: string;              // Type: all, function, hook, class, method
  get_details?: boolean;      // Fetch full documentation
  limit?: number;             // Max results (default: 5)
}

Response:

{
  "results": [
    {
      "name": "register_post_type",
      "type": "function",
      "description": "Registers a post type",
      "url": "https://developer.wordpress.org/reference/functions/register_post_type/"
    }
  ],
  "details": {
    "signature": "register_post_type( $post_type, $args )",
    "parameters": [...],
    "return": "WP_Post_Type|WP_Error",
    "source": "wp-includes/post.php"
  }
}

REST API Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600,
  "collections": 5,
  "total_vectors": 20450
}

List Available Tools

GET /tools

Response:

{
  "tools": [
    {
      "name": "search_codebase",
      "description": "Semantic search across repositories",
      "parameters": {
        "query": {"type": "string", "required": true},
        "project": {"type": "string", "required": false}
      }
    }
  ]
}

Metrics

GET /metrics

Response:

{
  "requests_total": 1250,
  "requests_by_tool": {
    "search_codebase": 800,
    "search_functions": 300,
    "search_wikit_blocks": 150
  },
  "average_response_time": "75ms",
  "cache_hit_rate": "45%"
}

Error Handling

Error Response Format

{
  "error": {
    "code": "COLLECTION_NOT_FOUND",
    "message": "Collection 'project_invalid' does not exist",
    "details": {
      "collection": "project_invalid",
      "available_collections": ["project_my_site", "wdg_framework"]
    }
  }
}

Error Codes

Code	Description
INVALID_PARAMETERS	Missing or invalid parameters
COLLECTION_NOT_FOUND	Requested collection doesn't exist
VECTOR_DB_ERROR	Qdrant database error
INDEXING_ERROR	Error during indexing process
INTERNAL_ERROR	Server error

Rate Limiting

Currently no rate limiting (local development).

For production deployments:

• 100 requests per minute per client
• Burst allowance: 20 requests

WebSocket Support

const ws = new WebSocket('ws://localhost:8765/ws');

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('Update:', data);
};

// Subscribe to indexing updates
ws.send(JSON.stringify({
    action: 'subscribe',
    events: ['indexing_complete', 'collection_updated']
}));

Client Libraries

Python

from wdg_mcp import Client

client = Client("http://localhost:8765")

# Search code
results = client.search_codebase(
    query="email validation",
    project="my-site",
    limit=10
)

# Get project info
info = client.get_project_info("my-site")

JavaScript/TypeScript

import { MCPClient } from '@wdg/mcp-client';

const client = new MCPClient('http://localhost:8765');

// Search code
const results = await client.searchCodebase({
    query: 'email validation',
    project: 'my-site',
    limit: 10
});

// Get project info
const info = await client.getProjectInfo('my-site');

Integration Examples

Claude Desktop

{
  "mcpServers": {
    "wdg": {
      "url": "http://localhost:8765",
      "tools": ["search_codebase", "search_functions", "get_project_info"]
    }
  }
}

Cursor IDE

{
  "servers": {
    "wdg": {
      "url": "http://localhost:8765",
      "name": "WDG AI Dev Environment"
    }
  }
}

---

See Also:

• MCP Server
• Indexer Internals
• Code Indexing