MCP 協議入門：讓 AI 使用你的工具

from mcp.server.fastmcp import FastMCP

# 建立 Server 實例
mcp = FastMCP("my-server")

@mcp.tool()
def hello(name: str) -> str:
    """
    打招呼

    Args:
        name: 要打招呼的對象
    """
    return f"Hello, {name}!"

# 執行（stdio 模式）
if __name__ == "__main__":
    mcp.run()

@mcp.tool()
async def my_tool(
    required_param: str,           # 必填參數
    optional_param: int = 10,      # 選填參數（有預設值）
) -> str:
    """
    工具的簡短描述（第一行會成為工具說明）

    Args:
        required_param: 必填參數的說明
        optional_param: 選填參數的說明，預設 10
    """
    # 工具邏輯
    return "結果"

@mcp.tool()
async def query_project(
    project_id: str | None = None,
    keyword: str | None = None,
) -> str:
    """
    查詢專案資訊

    Args:
        project_id: 專案 UUID（精確查詢）
        keyword: 關鍵字（模糊搜尋專案名稱）
    """
    await ensure_db_connection()

    async with get_connection() as conn:
        if project_id:
            # UUID 查詢
            row = await conn.fetchrow(
                "SELECT * FROM projects WHERE id = $1",
                UUID(project_id),
            )
            if not row:
                return f"找不到專案：{project_id}"
            return format_project(row)

        elif keyword:
            # 關鍵字搜尋
            rows = await conn.fetch(
                """
                SELECT * FROM projects
                WHERE name ILIKE $1
                ORDER BY updated_at DESC
                LIMIT 10
                """,
                f"%{keyword}%",
            )
            if not rows:
                return f"找不到包含「{keyword}」的專案"
            return "\n\n".join(format_project(row) for row in rows)

        else:
            return "請提供 project_id 或 keyword"

from ching_tech_os.services.mcp_server import get_mcp_tools

# 取得工具定義（符合 Claude API 格式）
tools = await get_mcp_tools()

# 結果範例
[
    {
        "name": "query_project",
        "description": "查詢專案資訊",
        "input_schema": {
            "type": "object",
            "properties": {
                "project_id": {"type": "string"},
                "keyword": {"type": "string"},
            },
        },
    },
    # ...
]

from ching_tech_os.services.mcp_server import execute_tool

# 執行工具
result = await execute_tool("query_project", {"keyword": "水切爐"})
print(result)
# 輸出：專案資訊...

# 建立專案
result = await execute_tool("create_project", {
    "name": "新專案",
    "description": "專案描述",
    "start_date": "2026-01-01",
})

import anthropic
from ching_tech_os.services.mcp_server import get_mcp_tools, execute_tool

client = anthropic.AsyncAnthropic()

# 取得工具定義
tools = await get_mcp_tools()

# 呼叫 Claude API
response = await client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=4096,
    tools=tools,
    messages=[{"role": "user", "content": "查詢水切爐專案"}],
)

# 處理工具調用
for block in response.content:
    if block.type == "tool_use":
        # 執行工具
        result = await execute_tool(block.name, block.input)
        # 將結果回傳給 Claude 繼續對話
        # ...

#!/usr/bin/env python
"""MCP Server CLI 入口點"""

from ching_tech_os.services.mcp_server import mcp

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