my-mcp-server/
├── pyproject.toml
├── src/
│   └── my_mcp_server/
│       ├── __init__.py
│       ├── server.py      # Main MCP server
│       ├── tools/         # Tool implementations
│       ├── utils/         # Shared utilities
│       └── schemas/       # Pydantic models
└── tests/

my-mcp-server/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts          # Main entry
│   ├── server.ts         # MCP server setup
│   ├── tools/            # Tool implementations
│   ├── utils/            # Shared utilities
│   └── types/            # Zod schemas
└── tests/

# Python example - shared utilities
from mcp.server import Server
from mcp.types import Tool, TextContent

class APIClient:
    """Handles auth, rate limiting, errors"""
    
    async def request(self, endpoint: str, **kwargs):
        # Retry logic, error handling
        pass

def format_response(data: dict) -> str:
    """Convert API response to agent-friendly format"""
    # Markdown or structured text
    pass

from pydantic import BaseModel, Field

class SearchParams(BaseModel):
    """Input schema with validation"""
    query: str = Field(..., description="Search query")
    limit: int = Field(10, ge=1, le=100)

@server.tool()
async def search_items(params: SearchParams) -> str:
    """
    Search for items in the database.
    
    Use this when you need to find items matching specific criteria.
    Returns a list of matching items with their IDs and summaries.
    """
    results = await client.search(params.query, params.limit)
    return format_as_markdown(results)

@server.tool(
    annotations={
        "readOnlyHint": True,      # Doesn't modify data
        "destructiveHint": False,  # Safe operation
        "idempotentHint": True,    # Same result if repeated
        "openWorldHint": False     # Operates on known data
    }
)
async def get_item(item_id: str) -> str:
    ...

class MCPError(Exception):
    """Base error with agent-friendly message"""
    
    def __init__(self, message: str, suggestion: str = None):
        self.message = message
        self.suggestion = suggestion

# Usage
raise MCPError(
    "Item not found",
    suggestion="Try searching with `search_items` first"
)

# Run server for testing
python -m my_mcp_server

# In another terminal, use MCP client to test