caddis-plugin: Instructions file for GitHub Copilot

MCP Server Development Guidelines

Standards for building Model Context Protocol servers using FastMCP for tool integration.

Overview

MCP servers provide tools, resources, and prompts that can be used by AI assistants. They enable:

• Tools: Functions the AI can call (database queries, file operations, API calls)
• Resources: Data the AI can access (files, database records, configurations)
• Prompts: Reusable prompt templates with parameters

---

Basic Structure

# mcp_server.py
from mcp.server.fastmcp import FastMCP

# Initialize the MCP server
mcp = FastMCP("<APP_NAME>-tools")

@mcp.tool()
def query_complaints(
    customer_id: str,
    status: str | None = None
) -> list[dict]:
    """
    Query complaints from the database.
    
    Args:
        customer_id: Customer ID to filter by
        status: Optional status filter (open, closed, pending)
    
    Returns:
        List of complaint records
    """
    from <SHARED_LIBS>.data import DatabaseAdapter
    
    adapter = DatabaseAdapter()
    query = "SELECT * FROM complaints WHERE customer_id = ?"
    params = [customer_id]
    
    if status:
        query += " AND status = ?"
        params.append(status)
    
    return adapter.fetch_records(query, params)

if __name__ == "__main__":
    mcp.run()

---

Tool Definition

Basic Tool

@mcp.tool()
def get_customer_info(customer_id: str) -> dict:
    """
    Retrieve customer information by ID.
    
    Args:
        customer_id: The unique customer identifier (e.g., CUST001)
    
    Returns:
        Customer record with name, email, and account status
    """
    adapter = DatabaseAdapter()
    result = adapter.fetch_one(
        "SELECT * FROM customers WHERE id = ?",
        (customer_id,)
    )
    
    if not result:
        return {"error": f"Customer {customer_id} not found"}
    
    return result

Tool with Complex Parameters

from pydantic import BaseModel, Field
from typing import Literal
from datetime import date

class ComplaintFilter(BaseModel):
    """Filter parameters for complaint search."""
    status: Literal["open", "closed", "pending"] | None = None
    priority: int | None = Field(None, ge=1, le=5)
    start_date: date | None = None
    end_date: date | None = None

@mcp.tool()
def search_complaints(
    customer_id: str,
    filters: ComplaintFilter | None = None,
    limit: int = 50
) -> list[dict]:
    """
    Search complaints with advanced filtering.
    
    Args:
        customer_id: Customer ID to search
        filters: Optional filter criteria
        limit: Maximum number of results (default 50)
    
    Returns:
        List of matching complaint records
    """
    query = "SELECT TOP (?) * FROM complaints WHERE customer_id = ?"
    params = [limit, customer_id]
    
    if filters:
        if filters.status:
            query += " AND status = ?"
            params.append(filters.status)
        if filters.priority:
            query += " AND priority = ?"
            params.append(filters.priority)
        if filters.start_date:
            query += " AND created_at >= ?"
            params.append(filters.start_date)
        if filters.end_date:
            query += " AND created_at <= ?"
            params.append(filters.end_date)
    
    adapter = DatabaseAdapter()
    return adapter.fetch_records(query, params)