有用的模型上下文协议服务器 (MCPS)

这是一系列独立的 Python 脚本，用于实现各种实用功能的模型上下文协议 (MCP) 服务器。每个服务器都提供专门的工具，可供 AI 助手或其他支持 MCP 协议的应用程序使用。

什么是 MCP？

模型上下文协议 (MCP) 是一种标准化的方式，供 AI 助手与外部工具和服务进行交互。它允许 AI 模型通过调用 MCP 服务器提供的专用功能来扩展其能力。通信通过标准输入/输出 (stdio) 使用 JSON 消息进行。

可用服务器

每个 MCP 服务器都设计为使用 Python 环境管理器（如 uv）运行。

YouTube 数据提取器 (ytdlp/ytdlp_mcp.py)

一个使用 yt-dlp 从 YouTube 视频中提取信息的服务器。

工具：

• 提取章节: 从 YouTube 视频中获取章节信息。
• 提取字幕: 从 YouTube 视频中获取特定章节或整个视频的字幕。

MCP 服务器配置：

"mcpServers": {
  "ytdlp": {
    "name": "youtube", // 客户端的可选友好名称
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/ytdlp", // 包含 pyproject.toml 的 MCP 目录的路径
      "--", // 脚本参数之前的分隔符（如果有）
      "ytdlp_mcp" // 匹配 pyproject.toml [project.scripts] 中定义的脚本名称
    ]
    // 使用 --directory 时不需要 'cwd'
  }
}

Word 文档处理器 (docx_replace/docx_replace_mcp.py)

一个用于操作 Word 文档的服务器，包括模板处理和 PDF 转换。

工具：

• 处理模板: 替换 Word 模板中的占位符并管理内容块。
• 获取模板键: 从 Word 文档模板中提取所有替换键。
• 转换为 PDF: 将 Word 文档 (docx) 转换为 PDF 格式。

MCP 服务器配置：

"mcpServers": {
  "docx_replace": {
    "name": "docx", // 可选的友好名称
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/docx_replace", // MCP 目录的路径
      "--",
      "docx_replace_mcp" // 匹配 pyproject.toml 中定义的脚本名称
    ]
  }
}

PlantUML 渲染器 (plantuml/src/plantuml_server/main.py)

一个使用 PlantUML 服务器（通常通过 Docker 运行）渲染 PlantUML 图表的服务器。

工具：

• 渲染图表: 将 PlantUML 文本转换为图表图像（例如，PNG）。

MCP 服务器配置：

"mcpServers": {
  "plantuml": {
    "name": "plantuml", // 可选的友好名称
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/plantuml", // MCP 目录的路径
      "--",
      "plantuml_server" // 匹配 pyproject.toml 中定义的脚本名称
    ]
  }
}

(注意：需要一个可访问的正在运行的 PlantUML 服务器，可能通过 Docker 管理，如服务中所实现的那样)。

Mermaid 渲染器 (mermaid/mermaid_mcp.py)

一个使用 mermaidchart.com API 渲染 Mermaid 图表的服务器。

工具：

• 渲染 Mermaid 图表: 通过在 mermaidchart.com 上创建文档，将 Mermaid 代码转换为 PNG 图像。

MCP 服务器配置：

"mcpServers": {
  "mermaid": {
    "name": "mermaid", // 可选的友好名称
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/mermaid", // MCP 目录的路径
      "--",
      "mermaid_mcp" // 匹配 pyproject.toml 中定义的脚本名称
    ],
    "env": { // MCP 需要的环境变量
        "MERMAID_CHART_ACCESS_TOKEN": "YOUR_API_TOKEN_HERE"
    }
  }
}

(注意：需要将 Mermaid Chart API 访问令牌设置为环境变量)。

安装

1. 克隆存储库：

   git clone https://github.com/daltonnyx/useful-mcps.git # 如果不同，请替换为实际的存储库 URL
   cd useful-mcps
   

2. 安装 uv： 如果您没有 uv，请安装它：

   pip install uv
   # 或按照 https://github.com/astral-sh/uv 上的说明进行操作
   

3. 依赖项： 依赖项通过 pyproject.toml 按 MCP 进行管理。当您第一次使用 --directory 运行 MCP 时，uv run 通常会自动在虚拟环境中处理它们的安装。

用法

运行服务器

建议使用 uv run --directory <path> 运行每个 MCP 服务器，指向特定 MCP 的目录。uv 根据在那里找到的 pyproject.toml 处理虚拟环境和依赖项。

示例（来自根 useful-mcps 目录）：

# 运行 YouTube MCP
uv run --directory ./ytdlp ytdlp_mcp

# 运行 Mermaid MCP（确保令牌已在环境中设置）
uv run --directory ./mermaid mermaid_mcp

或者，配置您的 MCP 客户端（如上面的 JSON 配置示例）以直接执行 uv run --directory ... 命令。

连接到服务器

配置您的 MCP 客户端应用程序，以使用每个服务器的“MCP 服务器配置”示例中显示的 command 和 args 结构启动所需的服务器。确保 command 指向您的 uv 可执行文件，并且 args 正确指定 --directory，其中包含 MCP 文件夹的路径和要运行的脚本名称。使用 env 属性传递必要的环境变量（如 API 令牌）。

工具特定用法示例

这些显示了您将发送到相应 MCP 服务器的 call_tool 函数的示例 arguments。

YouTube 数据提取器

提取章节

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

提取字幕

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "language": "en",
  "chapters": [
    {
      "title": "Introduction",
      "start_time": "00:00:00",
      "end_time": "00:01:30"
    }
  ]
}

Word 文档处理器

处理模板

{
  "template_file": "/path/to/template.docx",
  "replacements": {
    "name": "John Doe",
    "date": "2023-05-15"
  },
  "blocks": {
    "optional_section": true,
    "alternative_section": false
  },
  "output_filename": "/path/to/output.docx"
}

(注意：template_file 和 docx_file 也可以接受 base64 编码的字符串，而不是路径)

获取模板键

{
  "template_file": "/path/to/template.docx"
}

转换为 PDF

{
  "docx_file": "/path/to/document.docx",
  "pdf_output": "/path/to/output.pdf"
}

PlantUML 渲染器

渲染图表

{
  "input": "participant User\nUser -> Server: Request\nServer --> User: Response",
  "output_path": "/path/to/save/diagram.png"
}

(注意：input 也可以是 .puml 文件的路径)

Mermaid 渲染器

渲染 Mermaid 图表

{
  "mermaid_code": "graph TD;\n    A-->B;\n    A-->C;\n    B-->D;\n    C-->D;",
  "output_path": "/path/to/save/mermaid.png",
  "theme": "default" // 可选，例如 "default", "dark", "neutral", "forest"
}

开发

添加新的 MCP 服务器

1. 为您的 MCP 创建一个新目录（例如，my_new_mcp）。
2. 在目录中，创建：
   • pyproject.toml：定义项目元数据、依赖项和脚本入口点（例如，[project.scripts] 部分映射 my_new_mcp = "my_new_mcp:main"）。
   • pyrightconfig.json：（可选）用于类型检查。
   • 您的主 Python 文件（例如，my_new_mcp.py）：使用 mcp 库实现 MCP 逻辑（请参阅下面的模板）。
3. 实现所需的类和函数 (serve, list_tools, call_tool)。

基本模板 (my_new_mcp.py):

import json
import logging
import asyncio
from typing import List, Dict, Any, Optional
# Assuming mcp library is installed or available
# from mcp import Server, Tool, TextContent, stdio_server
# Placeholder imports if mcp library structure is different
from typing import Protocol # Using Protocol as placeholder

# Placeholder definitions if mcp library isn't directly importable here
class Tool(Protocol):
    name: str
    description: str
    inputSchema: dict

class TextContent(Protocol):
    type: str
    text: str

class Server:
    def __init__(self, name: str): pass
    def list_tools(self): pass # Decorator
    def call_tool(self): pass # Decorator
    def create_initialization_options(self): pass
    async def run(self, read_stream, write_stream, options): pass

# Placeholder context manager
class stdio_server:
    async def __aenter__(self): return (None, None) # Dummy streams
    async def __aexit__(self, exc_type, exc, tb): pass


# Pydantic is often used for schema definition
# from pydantic import BaseModel
# class MyInput(BaseModel):
#     param1: str
#     param2: int

class MyInputSchema: # Placeholder if not using Pydantic
    @staticmethod
    def model_json_schema():
      return {"type": "object", "properties": {"param1": {"type": "string"}, "param2": {"type": "integer"}}, "required": ["param1", "param2"]}


class MyTools:
    TOOL_NAME = "my.tool"

class MyService:
    def __init__(self):
        # Initialize resources if needed
        pass

    def my_function(self, param1: str, param2: int) -> dict:
        # Implement your tool functionality
        logging.info(f"Running my_function with {param1=}, {param2=}")
        # Replace with actual logic
        result_content = f"Result: processed {param1} and {param2}"
        return {"content": result_content}

async def serve() -> None:
    logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
    server = Server("mcp-my-service")
    service = MyService()

    @server.list_tools()
    async def list_tools() -> list[Tool]:
        logging.info("list_tools called")
        return [
            Tool(
                name=MyTools.TOOL_NAME,
                description="Description of my tool",
                # Use Pydantic's schema or manually define
                inputSchema=MyInputSchema.model_json_schema(),
            ),
        ]

    @server.call_tool()
    async def call_tool(name: str, arguments: dict) -> list[TextContent]:
        logging.info(f"call_tool called with {name=}, {arguments=}")
        try:
            if name == MyTools.TOOL_NAME:
                # Add validation here if not using Pydantic
                param1 = arguments.get("param1")
                param2 = arguments.get("param2")
                if param1 is None or param2 is None:
                     raise ValueError("Missing required arguments")

                result = service.my_function(param1, int(param2)) # Ensure type conversion if needed
                logging.info(f"Tool executed successfully: {result=}")
                return [TextContent(type="text", text=json.dumps(result))] # Return JSON string
            else:
                logging.warning(f"Unknown tool requested: {name}")
                raise ValueError(f"Unknown tool: {name}")
        except Exception as e:
            logging.error(f"Error executing tool {name}: {e}", exc_info=True)
            # Return error as JSON
            error_payload = json.dumps({"error": str(e)})
            return [TextContent(type="text", text=error_payload)]

    options = server.create_initialization_options()
    logging.info("Starting MCP server...")
    async with stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream, options)
    logging.info("MCP server stopped.")

def main():
    # Entry point defined in pyproject.toml `[project.scripts]`
    try:
        asyncio.run(serve())
    except KeyboardInterrupt:
        logging.info("Server interrupted by user.")

if __name__ == "__main__":
    # Allows running directly via `python my_new_mcp.py` for debugging
    main()

测试

使用 pytest 从根目录运行测试：

pytest tests/

(确保已安装测试依赖项，可能通过 uv pip install pytest 或通过将 pytest 添加到其中一个 pyproject.toml 文件中的开发依赖项)。

许可证

MIT 许可证

贡献

欢迎贡献！请随时提交 Pull Request。