Useful Model Context Protocol Servers (MCPS)

实用的 Model Context Protocol 服务（MCPS）

一组独立的 Python 脚本，用于实现各类实用功能的 Model Context Protocol （MCP）服务。每个服务都提供专用工具，可供 AI 助手或其他支持 MCP 协议的应用程序使用。

什么是 MCP？

Model Context Protocol（MCP）是一种标准化方式，让 AI 助手能够与外部工具和服务交互。它允许 AI 模型通过调用 MCP 服务提供的专用函数来扩展自身能力。 通信通过标准输入/输出（stdio）使用 JSON 消息进行。

可用服务

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

YouTube 数据提取器（ytdlp）

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

工具：

• 提取章节：获取 YouTube 视频的章节信息。
• 提取字幕：获取 YouTube 视频的字幕，可指定章节或提取整个视频的字幕。

MCP 服务配置：

"mcpServers": {
  "ytdlp": {
    "name": "youtube", // Optional friendly name for the client
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/ytdlp", // Path to the MCP directory containing pyproject.toml
      "--", // Separator before script arguments, if any
      "ytdlp_mcp" // Match the script name defined in pyproject.toml [project.scripts]
    ]
    // 'cwd' is not needed when using --directory
  }
}

Word 文档处理器（docx_replace）

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

工具：

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

MCP 服务配置：

"mcpServers": {
  "docx_replace": {
    "name": "docx", // Optional friendly name
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/docx_replace", // Path to the MCP directory
      "--",
      "docx_replace_mcp" // Match the script name defined in pyproject.toml
    ]
  }
}

PlantUML 渲染器（plantuml）

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

工具：

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

MCP 服务配置：

"mcpServers": {
  "plantuml": {
    "name": "plantuml", // Optional friendly name
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/plantuml", // Path to the MCP directory
      "--",
      "plantuml_server" // Match the script name defined in pyproject.toml
    ]
  }
}

（注意：需要可访问的运行中 PlantUML 服务；该服务可能通过 Docker 管理，具体实现见服务。）

Mermaid 渲染器（mermaid）

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

工具：

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

MCP 服务配置：

"mcpServers": {
  "mermaid": {
    "name": "mermaid", // Optional friendly name
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/mermaid", // Path to the MCP directory
      "--",
      "mermaid_mcp" // Match the script name defined in pyproject.toml
    ],
    "env": { // Environment variables needed by the MCP
        "MERMAID_CHART_ACCESS_TOKEN": "YOUR_API_TOKEN_HERE"
    }
  }
}

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

RSS 转 Markdown（rss2md）

一个将 RSS 源内容转换为 Markdown 格式并按日期筛选的服务。

工具：

• fetch_rss_to_markdown：获取 RSS 源，按日期筛选文章，并以 Markdown 列表格式返回符合条件的文章。。

MCP 服务配置：

"mcpServers": {
  "mermaid": {
    "name": "rss2md", // Optional friendly name
    "command": "uv",
    "args": [
      "run",
      "--directory", "<path/to/repo>/useful-mcps/rss2md", // Path to the MCP directory
      "--",
      "rss2md_mcp" // Match the script name defined in pyproject.toml
    ],
    "env": { // Environment variables needed by the MCP
    }
  }
}

安装

1. 克隆代码仓库：

   git clone https://github.com/daltonnyx/useful-mcps.git # Replace with the actual repo URL if different
   cd useful-mcps
   

2. **安装 uv：**如果尚未安装 uv，请进行安装：

   pip install uv
   # or follow instructions at https://github.com/astral-sh/uv
   

3. **依赖项：**各 MCP 的依赖项通过 pyproject.toml 单独管理。 首次使用 --directory 运行 MCP 时，uv run 通常会在虚拟环境中自动安装依赖项。

使用方法

运行服务

建议使用 uv run --directory <path> 运行每个 MCP 服务，并将 <path> 指向对应 MCP 的目录。uv 会根据该目录中的 pyproject.toml 管理虚拟环境和依赖项。

示例（在根目录 useful-mcps 中运行）：

# Run the YouTube MCP
uv run --directory ./ytdlp ytdlp_mcp

# Run the Mermaid MCP (ensure token is set in environment)
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 Data Extractor

提取章节

{
  "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 Document Processor

处理模板

{
  "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 Renderer

渲染图表

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

（注意：input 也可以是 .puml 文件的路径）

Mermaid Renderer

渲染 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" // Optional, e.g., "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。