aigroup-workflow 2.1.2 → 2.2.0

package/skills/infra/mcp-developer/references/protocol.md

@@ -0,0 +1,244 @@
+# MCP Protocol Specification
+
+## Protocol Overview
+
+MCP is built on JSON-RPC 2.0 and enables bidirectional communication between clients (like Claude Desktop) and servers that provide resources, tools, and prompts.
+
+## Message Types
+
+### Request/Response
+
+```typescript
+// Request format
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/list",
+  "params": {}
+}
+
+// Success response
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "tools": [
+      {
+        "name": "get_weather",
+        "description": "Get weather for a location",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "location": { "type": "string" }
+          },
+          "required": ["location"]
+        }
+      }
+    ]
+  }
+}
+
+// Error response
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32602,
+    "message": "Invalid params",
+    "data": { "details": "location is required" }
+  }
+}
+```
+
+### Notifications
+
+```typescript
+// Server sends notification (no response expected)
+{
+  "jsonrpc": "2.0",
+  "method": "notifications/resources/updated",
+  "params": {
+    "uri": "file:///project/data.json"
+  }
+}
+```
+
+## Connection Lifecycle
+
+```
+1. Client initiates connection (stdio/HTTP/SSE)
+2. Client sends initialize request
+   → Server responds with capabilities
+3. Client sends initialized notification
+4. Normal operation (requests/notifications)
+5. Client/server can ping for keepalive
+6. Client sends shutdown request
+7. Connection closes
+```
+
+### Initialize Handshake
+
+```typescript
+// Client initialize request
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {
+      "roots": { "listChanged": true },
+      "sampling": {}
+    },
+    "clientInfo": {
+      "name": "claude-desktop",
+      "version": "1.0.0"
+    }
+  }
+}
+
+// Server response
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {
+      "resources": { "subscribe": true, "listChanged": true },
+      "tools": { "listChanged": true },
+      "prompts": { "listChanged": true }
+    },
+    "serverInfo": {
+      "name": "my-mcp-server",
+      "version": "1.0.0"
+    }
+  }
+}
+
+// Client sends initialized notification
+{
+  "jsonrpc": "2.0",
+  "method": "notifications/initialized"
+}
+```
+
+## Core Methods
+
+### Resources
+
+```typescript
+// List available resources
+resources/list → { resources: Resource[] }
+
+// Read resource content
+resources/read { uri: string } → { contents: ResourceContent[] }
+
+// Subscribe to resource updates (if supported)
+resources/subscribe { uri: string } → {}
+
+// Unsubscribe
+resources/unsubscribe { uri: string } → {}
+
+// Server notifies of changes
+notifications/resources/list_changed → {}
+notifications/resources/updated { uri: string } → {}
+```
+
+### Tools
+
+```typescript
+// List available tools
+tools/list → { tools: Tool[] }
+
+// Execute tool
+tools/call {
+  name: string,
+  arguments: object
+} → { content: ToolResponse[] }
+
+// Server notifies of tool changes
+notifications/tools/list_changed → {}
+```
+
+### Prompts
+
+```typescript
+// List available prompts
+prompts/list → { prompts: Prompt[] }
+
+// Get prompt with arguments
+prompts/get {
+  name: string,
+  arguments?: object
+} → { messages: PromptMessage[] }
+
+// Server notifies of prompt changes
+notifications/prompts/list_changed → {}
+```
+
+## Error Codes
+
+Standard JSON-RPC 2.0 codes plus MCP-specific:
+
+```typescript
+const ERROR_CODES = {
+  // JSON-RPC 2.0 standard
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+
+  // MCP-specific (implementation defined)
+  RESOURCE_NOT_FOUND: -32001,
+  TOOL_EXECUTION_ERROR: -32002,
+  UNAUTHORIZED: -32003,
+  RATE_LIMIT_EXCEEDED: -32004
+};
+```
+
+## Transport Mechanisms
+
+### stdio (Standard Input/Output)
+
+```typescript
+// Server reads from stdin, writes to stdout
+// Each message is newline-delimited JSON
+// Used for local integration (Claude Desktop default)
+```
+
+### HTTP with SSE (Server-Sent Events)
+
+```typescript
+// Client POSTs JSON-RPC requests to endpoint
+// Server streams responses and notifications via SSE
+// Used for remote servers
+
+POST /mcp HTTP/1.1
+Content-Type: application/json
+
+{"jsonrpc":"2.0","id":1,"method":"tools/list"}
+
+// SSE response
+GET /mcp/sse HTTP/1.1
+
+event: message
+data: {"jsonrpc":"2.0","id":1,"result":{...}}
+```
+
+## Protocol Versions
+
+Current version: `2024-11-05`
+
+Servers must declare supported version in initialize response. Clients should verify compatibility.
+
+## Best Practices
+
+1. **Validation**: Always validate params with JSON Schema
+2. **Error handling**: Return structured errors with helpful messages
+3. **Versioning**: Check protocol version in initialize
+4. **Timeouts**: Implement request timeouts (30s recommended)
+5. **Logging**: Log all protocol messages for debugging
+6. **Stateless**: Design tools/resources to be stateless
+7. **Idempotency**: Make tool calls idempotent when possible
+8. **Notifications**: Use notifications for real-time updates

package/skills/infra/mcp-developer/references/python-sdk.md

@@ -0,0 +1,367 @@
+# Python SDK Implementation
+
+## Installation
+
+```bash
+pip install mcp pydantic
+```
+
+## Basic Server Setup
+
+```python
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import (
+    Tool,
+    TextContent,
+    CallToolRequest,
+    ListToolsRequest,
+)
+from pydantic import BaseModel, Field
+import asyncio
+
+# Create server instance
+app = Server("example-server")
+
+# Define tool input schema
+class WeatherArgs(BaseModel):
+    location: str = Field(..., description="City name or zip code")
+    units: str = Field(default="celsius", pattern="^(celsius|fahrenheit)$")
+
+# List available tools
+@app.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="get_weather",
+            description="Get current weather for a location",
+            inputSchema=WeatherArgs.model_json_schema(),
+        )
+    ]
+
+# Handle tool execution
+@app.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    if name == "get_weather":
+        # Validate arguments
+        args = WeatherArgs(**arguments)
+
+        # Execute tool logic
+        weather_data = await fetch_weather(args.location, args.units)
+
+        return [
+            TextContent(
+                type="text",
+                text=f"Weather in {args.location}: {weather_data['temp']}°{
+                    'C' if args.units == 'celsius' else 'F'
+                }",
+            )
+        ]
+
+    raise ValueError(f"Unknown tool: {name}")
+
+# Run server
+async def main():
+    async with stdio_server() as (read_stream, write_stream):
+        await app.run(
+            read_stream,
+            write_stream,
+            app.create_initialization_options(),
+        )
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Resource Provider
+
+```python
+from mcp.types import (
+    Resource,
+    ResourceTemplate,
+    TextResourceContents,
+    ListResourcesRequest,
+    ReadResourceRequest,
+)
+import json
+
+@app.list_resources()
+async def list_resources() -> list[Resource]:
+    return [
+        Resource(
+            uri="file:///config/settings.json",
+            name="Application Settings",
+            description="Current application configuration",
+            mimeType="application/json",
+        ),
+        Resource(
+            uri="db://users/schema",
+            name="User Schema",
+            description="Database schema for users table",
+            mimeType="text/plain",
+        ),
+    ]
+
+@app.read_resource()
+async def read_resource(uri: str) -> str:
+    if uri == "file:///config/settings.json":
+        settings = await load_settings()
+        return json.dumps(settings, indent=2)
+
+    if uri.startswith("db://users/"):
+        schema = await get_database_schema("users")
+        return schema
+
+    raise ValueError(f"Resource not found: {uri}")
+```
+
+## Resource Templates (Dynamic URIs)
+
+```python
+@app.list_resource_templates()
+async def list_resource_templates() -> list[ResourceTemplate]:
+    return [
+        ResourceTemplate(
+            uriTemplate="user://{user_id}/profile",
+            name="User Profile",
+            description="Get user profile by ID",
+            mimeType="application/json",
+        )
+    ]
+
+@app.read_resource()
+async def read_resource(uri: str) -> str:
+    # Parse template URI
+    if uri.startswith("user://"):
+        user_id = uri.split("/")[2]
+        profile = await get_user_profile(user_id)
+        return json.dumps(profile, indent=2)
+
+    raise ValueError(f"Unknown resource: {uri}")
+```
+
+## Prompt Templates
+
+```python
+from mcp.types import (
+    Prompt,
+    PromptArgument,
+    PromptMessage,
+    GetPromptRequest,
+)
+
+@app.list_prompts()
+async def list_prompts() -> list[Prompt]:
+    return [
+        Prompt(
+            name="code_review",
+            description="Generate code review comments",
+            arguments=[
+                PromptArgument(
+                    name="language",
+                    description="Programming language",
+                    required=True,
+                ),
+                PromptArgument(
+                    name="code",
+                    description="Code to review",
+                    required=True,
+                ),
+            ],
+        )
+    ]
+
+@app.get_prompt()
+async def get_prompt(name: str, arguments: dict) -> list[PromptMessage]:
+    if name == "code_review":
+        language = arguments["language"]
+        code = arguments["code"]
+
+        return [
+            PromptMessage(
+                role="user",
+                content=TextContent(
+                    type="text",
+                    text=f"Review this {language} code and provide feedback:\n\n{code}",
+                ),
+            )
+        ]
+
+    raise ValueError(f"Unknown prompt: {name}")
+```
+
+## Input Validation with Pydantic
+
+```python
+from pydantic import BaseModel, Field, field_validator
+from typing import Literal
+
+class WeatherArgs(BaseModel):
+    location: str = Field(..., min_length=1, description="City name")
+    units: Literal["celsius", "fahrenheit"] = Field(default="celsius")
+
+    @field_validator("location")
+    @classmethod
+    def validate_location(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("Location cannot be empty")
+        return v.strip()
+
+class DatabaseQueryArgs(BaseModel):
+    table: str = Field(..., pattern="^[a-zA-Z_][a-zA-Z0-9_]*$")
+    limit: int = Field(default=100, ge=1, le=1000)
+    offset: int = Field(default=0, ge=0)
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    if name == "query_database":
+        # Pydantic validation happens here
+        args = DatabaseQueryArgs(**arguments)
+
+        results = await execute_query(args.table, args.limit, args.offset)
+        return [TextContent(type="text", text=json.dumps(results))]
+
+    raise ValueError(f"Unknown tool: {name}")
+```
+
+## Error Handling
+
+```python
+from mcp.types import McpError, INTERNAL_ERROR, INVALID_PARAMS
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    try:
+        if name == "get_weather":
+            args = WeatherArgs(**arguments)
+            result = await fetch_weather(args.location, args.units)
+            return [TextContent(type="text", text=str(result))]
+
+        raise ValueError(f"Unknown tool: {name}")
+
+    except ValueError as e:
+        # Validation or tool not found
+        raise McpError(INVALID_PARAMS, str(e))
+
+    except Exception as e:
+        # Unexpected errors
+        raise McpError(INTERNAL_ERROR, f"Tool execution failed: {e}")
+```
+
+## Logging
+
+```python
+import logging
+import sys
+
+# Configure logging to stderr (stdout is used for protocol)
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    stream=sys.stderr,
+)
+
+logger = logging.getLogger("mcp-server")
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    logger.info(f"Tool called: {name} with args: {arguments}")
+
+    try:
+        result = await execute_tool(name, arguments)
+        logger.info(f"Tool {name} completed successfully")
+        return result
+    except Exception as e:
+        logger.error(f"Tool {name} failed: {e}", exc_info=True)
+        raise
+```
+
+## Context Managers and Cleanup
+
+```python
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def database_connection():
+    """Manage database connection lifecycle"""
+    db = await connect_to_database()
+    try:
+        yield db
+    finally:
+        await db.close()
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    if name == "query_database":
+        async with database_connection() as db:
+            result = await db.execute(arguments["query"])
+            return [TextContent(type="text", text=str(result))]
+
+    raise ValueError(f"Unknown tool: {name}")
+```
+
+## Basic Client Setup
+
+```python
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+async def run_client():
+    server_params = StdioServerParameters(
+        command="python",
+        args=["server.py"],
+    )
+
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            # Initialize connection
+            await session.initialize()
+
+            # List available tools
+            tools = await session.list_tools()
+            print(f"Available tools: {[t.name for t in tools.tools]}")
+
+            # Call a tool
+            result = await session.call_tool(
+                "get_weather",
+                arguments={"location": "San Francisco"},
+            )
+            print(f"Result: {result.content}")
+
+if __name__ == "__main__":
+    asyncio.run(run_client())
+```
+
+## Notifications
+
+```python
+from mcp.types import ResourceUpdatedNotification
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    if name == "update_config":
+        # Update configuration
+        await save_config(arguments["config"])
+
+        # Notify clients of resource update
+        await app.request_context.session.send_resource_updated(
+            uri="file:///config/settings.json"
+        )
+
+        return [TextContent(type="text", text="Configuration updated")]
+
+    raise ValueError(f"Unknown tool: {name}")
+```
+
+## Best Practices
+
+1. **Type Safety**: Use Pydantic for all schemas
+2. **Async/Await**: All handlers must be async
+3. **Validation**: Validate inputs early with Pydantic
+4. **Logging**: Log to stderr, never stdout
+5. **Error Handling**: Wrap errors in McpError
+6. **Resource Cleanup**: Use context managers
+7. **Testing**: Use pytest-asyncio for async tests
+8. **Performance**: Cache expensive operations
+9. **Security**: Sanitize all inputs and outputs
+10. **Documentation**: Include docstrings and type hints