📝 更新MCP文档，增强内容与示例

- 修改了MCP接口标准部分，增加了对OpenAI API风格与MCP的比较，提升文档的实用性与可读性。
- 优化了MCP功能描述，新增采样功能的说明，增强对MCP服务器功能的理解。
- 更新了代码示例，提供了更清晰的Echo服务器实现，提升示例的可操作性。
- 增加了配置文件示例，简化了MCP服务器的配置说明，提升文档的易用性。
- 精简了最佳实践部分，确保信息的清晰度与准确性。

Author: jiangyangcreate

docs/docs/后端通识/接口开发.md

@@ -17,14 +17,13 @@ API，全称为 **应用程序编程接口**（Application Programming Interface
 
 ### 接口标准
 
-
-| 维度 | **RESTful API** |**RPC** |
-|------|----------------|------------------|
-| **设计理念** | 资源为中心（GET /users） | **操作为中心**（调用 `run_code_analysis`） |
-| **AI 工具友好性** | ⚠️ 一般（需映射工具为资源） |  ✅ **极佳**（直接暴露函数，参数即输入） |
-| **自动文档 & 发现** | ✅ OpenAPI（Swagger）成熟 |  ✅ MCP 支持 `list-tools` / JSON Schema |
-| **典型用例** | 模型推理 API / 向量数据库查询 / 用户管理 |MCP 工具插件 / Cursor 自定义命令 / LLM 函数调用 |
-
+| 特性 | **OpenAI API 风格** | **MCP** | **OpenAPI** |
+|------|-------------------|---------|-------------|
+| **类型** | 商业 API 设计 | 开放通信协议 | 开放 API 描述规范 |
+| **是否开放治理** | ❌（OpenAI 控制） | ✅（社区驱动） | ✅（Linux 基金会） |
+| **是否可自由实现** | ⚠️（法律风险模糊） | ✅（MIT 许可） | ✅ |
+| **是否有正式规范文档** | ✅（但非标准组织发布） | ✅（mcp.spec） | ✅（openapis.org） |
+| **目标** | 调用 LLM | LLM 与工具通信 | 描述 RESTful API |
 
 ### 开发框架
 
@@ -517,219 +516,90 @@ if __name__ == '__main__':
     uvicorn.run(app, host=ip_host2, port=80)
 ```
 
-### MCP
+## MCP
 
-**Model Context Protocol（MCP）** 是一种开放协议，旨在标准化应用程序与大型语言模型（LLM）之间的上下文交互。属于 RPC 风格。
+**Model Context Protocol（MCP）** 是一种开放协议，旨在标准化应用程序与大型语言模型（LLM）之间的上下文交互。
 
-通过 MCP，开发者可以为 LLM 提供结构化的上下文信息、工具和资源，从而增强模型的功能和性能。
+MCP最初设计的对象是<Highlight>各类AI客户端（如 Claude Desktop、Cursor）,客户端通过配置文件连接 MCP 服务器</Highlight>。
 
-MCP 服务器可以暴露三种主要类型的功能：
+MCP 服务器可以暴露多种类型的功能：
 
 - **Resources（资源）：** 只读数据源，如文件内容、数据库查询结果等
 - **Tools（工具）：** LLM 可以调用的函数，用于执行操作或获取动态数据
 - **Prompts（提示词）：** 预定义的提示词模板，可供 LLM 使用
+- **Sampling(采样)：** 工具可反向调用大模型为自己生成一些内容
 
-#### 安装
-
-可以使用 `uv` 快速安装：`uv add "mcp[cli]"`
+并不是所有的主要类型功能都被支持，其中Tools支持范围最广。
 
+为了更快速的构建MCP，可以使用FastMCP 处理所有复杂的协议细节，专注于构建。大多数情况下，只需装饰一个 Python 函数即可，FastMCP 会处理剩下的工作。
 
-#### 快速开始
+参考地址：https://github.com/jlowin/fastmcp
 
-使用 FastMCP 快速创建一个 MCP 服务器：
+### 代码示例
 
-```python showLineNumbers
-from mcp.server.fastmcp import FastMCP
+```python showLineNumbers title="file_server.py"
+"""
+FastMCP Echo Server
+"""
 
-mcp = FastMCP("计算器服务")
+from fastmcp import FastMCP
 
-@mcp.tool()
-def add(a: float, b: float) -> float:
-    """返回两个数字的和"""
-    return a + b
+# Create server
+mcp = FastMCP("Echo Server")
 
-if __name__ == "__main__":
-    mcp.run()
-```
 
-#### 客户端调用
+@mcp.tool
+def echo_tool(text: str) -> str:
+    """Echo the input text"""
+    return text
 
-```python showLineNumbers
-from mcp.client 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:
-            await session.initialize()
-            
-            # 列出工具
-            tools = await session.list_tools()
-            
-            # 调用工具
-            result = await session.call_tool("add", {"a": 1, "b": 2})
-            print(f"结果: {result.content}")
 
-if __name__ == "__main__":
-    import asyncio
-    asyncio.run(run_client())
-```
+@mcp.resource("echo://static")
+def echo_resource() -> str:
+    return "Echo!"
 
-#### 生产级示例：文件系统服务器
 
-```python showLineNumbers
-from mcp.server.fastmcp import FastMCP
-import os
-import fnmatch
-from pathlib import Path
-
-mcp = FastMCP("文件系统服务")
-
-# 配置允许访问的根目录（安全限制）
-ALLOWED_ROOTS = ["/home/user/documents", "/home/user/projects"]
-
-def validate_path(path: str) -> Path:
-    """验证路径是否在允许的范围内"""
-    abs_path = Path(path).resolve()
-    
-    # 检查是否在允许的根目录内
-    if not any(abs_path.is_relative_to(root) for root in ALLOWED_ROOTS):
-        raise PermissionError(f"访问被拒绝: {path}")
-    
-    return abs_path
-
-@mcp.resource("file://{path}")
-def read_file(path: str) -> str:
-    """读取文件内容"""
-    validated_path = validate_path(path)
-    
-    if not validated_path.exists():
-        raise FileNotFoundError(f"文件不存在: {path}")
-    
-    if not validated_path.is_file():
-        raise ValueError(f"不是文件: {path}")
-    
-    # 限制文件大小（例如最大 10MB）
-    if validated_path.stat().st_size > 10 * 1024 * 1024:
-        raise ValueError(f"文件过大: {path}")
-    
-    with open(validated_path, 'r', encoding='utf-8') as f:
-        return f.read()
-
-@mcp.tool()
-def list_directory(path: str, include_hidden: bool = False) -> dict:
-    """列出目录内容"""
-    validated_path = validate_path(path)
-    
-    if not validated_path.is_dir():
-        raise ValueError(f"不是目录: {path}")
-    
-    files = []
-    dirs = []
-    
-    for item in validated_path.iterdir():
-        if not include_hidden and item.name.startswith('.'):
-            continue
-        
-        if item.is_file():
-            files.append({
-                "name": item.name,
-                "size": item.stat().st_size,
-                "modified": item.stat().st_mtime
-            })
-        elif item.is_dir():
-            dirs.append(item.name)
-    
-    return {
-        "path": str(path),
-        "directories": sorted(dirs),
-        "files": sorted(files, key=lambda x: x['name'])
-    }
+@mcp.resource("echo://{text}")
+def echo_template(text: str) -> str:
+    """Echo the input text"""
+    return f"Echo: {text}"
 
-@mcp.tool()
-def search_files(directory: str, pattern: str, max_results: int = 100) -> list[str]:
-    """搜索文件（支持通配符）"""
-    validated_path = validate_path(directory)
-    
-    if not validated_path.is_dir():
-        raise ValueError(f"不是目录: {directory}")
-    
-    matches = []
-    count = 0
-    
-    for root, dirs, files in os.walk(validated_path):
-        # 跳过隐藏目录
-        dirs[:] = [d for d in dirs if not d.startswith('.')]
-        
-        for filename in fnmatch.filter(files, pattern):
-            if count >= max_results:
-                break
-            matches.append(os.path.join(root, filename))
-            count += 1
-        
-        if count >= max_results:
-            break
-    
-    return matches
-
-@mcp.tool()
-def get_file_info(path: str) -> dict:
-    """获取文件详细信息"""
-    validated_path = validate_path(path)
-    
-    if not validated_path.exists():
-        raise FileNotFoundError(f"文件不存在: {path}")
-    
-    stat = validated_path.stat()
-    
-    return {
-        "path": str(path),
-        "name": validated_path.name,
-        "type": "file" if validated_path.is_file() else "directory",
-        "size": stat.st_size,
-        "created": stat.st_ctime,
-        "modified": stat.st_mtime,
-        "permissions": oct(stat.st_mode)[-3:]
-    }
 
-if __name__ == "__main__":
-    mcp.run()
+@mcp.prompt("echo")
+def echo_prompt(text: str) -> str:
+    return text
 ```
 
-#### 配置文件
+### 配置文件
 
-客户端（如 Claude Desktop、Cursor）通过配置文件连接 MCP 服务器：
+上面的代码我部署在`https://fastmcp.cloud/`中，下面的地址是其为我随机分配的。填入cursor后登录验证即可。
 
 ```json showLineNumbers
 {
   "mcpServers": {
-    "filesystem": {
-      "command": "python",
-      "args": ["file_server.py"],
-      "env": {
-        "ALLOWED_PATHS": "/home/user/documents"
-      }
+    "fastmcp": {
+      "url": "https://magnificent-crimson-antlion.fastmcp.app/mcp",
+      "transport": "http"
     }
   }
 }
 ```
 
-#### 最佳实践
+如果是通过放在本地，则只需要配置全局的`fastmcp`,确保路径正确即可。
 
-1. **工具命名：** 使用描述性的名称，遵循 `category.action` 模式（如 `file.read`、`database.query`）
-2. **输入验证：** 使用 JSON Schema 严格定义工具参数
-3. **错误处理：** 提供清晰的错误消息，帮助 LLM 理解问题
-4. **文档：** 为每个工具、资源和提示词提供详细的描述
-5. **安全性：** 验证输入参数，避免路径遍历、SQL 注入等安全问题
-6. **性能：** 对于耗时操作，使用异步函数和进度通知
-7. **日志记录：** 适当使用日志帮助调试和监控
+```json showLineNumbers
+{
+  "mcpServers": {
+    "local-echo-server": {
+      "command": "fastmcp",
+      "args": ["run", "C:\\Users\\allen\\Desktop\\MCP\\server.py"],
+      "transport": "stdio"
+    }
+  }
+}
+```
 
-MCP 协议为 LLM 应用提供了强大的扩展能力，使 AI 助手能够安全、标准化地访问外部资源和执行操作。更多信息请参考 [MCP 官方文档](https://modelcontextprotocol.github.io/python-sdk/api/) 和 [PyPI 包页面](https://pypi.org/project/mcp/)。
+更多信息请参考 [MCP 官方文档](https://modelcontextprotocol.github.io/python-sdk/api/) 和 [PyPI 包页面](https://pypi.org/project/mcp/)。
 
 
 ## Django