有用的模型上下文协议服务器（MCPS）
一组独立的 Python 脚本，用于实现模型上下文协议 (MCP) 服务器，以实现各种实用功能。每个服务器都提供专用工具，可供 AI 助手或其他支持 MCP 协议的应用程序使用。
什么是 MCP？
模型上下文协议 (MCP) 是 AI 助手与外部工具和服务交互的标准化方式。它允许 AI 模型通过调用 MCP 服务器提供的专用函数来扩展其功能。通信通过标准输入/输出 (stdio) 使用 JSON 消息进行。
可用服务器
每个 MCP 服务器都设计为使用 Python 环境管理器（如uv运行。
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 ）
使用 mermaidchart.com API 渲染美人鱼图表的服务器。
工具：
- 渲染美人鱼图表：通过在 mermaidchart.com 上创建文档将美人鱼代码转换为 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 格式的服务器。
工具：
- 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
}
}
}
安装
- 克隆存储库：
git clone https://github.com/daltonnyx/useful-mcps.git # Replace with the actual repo URL if different
cd useful-mcps
- **安装
uv ：**如果您没有uv ，请安装它：pip install uv
# or follow instructions at https://github.com/astral-sh/uv
- **依赖项：**依赖项通过
pyproject.toml按 MCP 进行管理。当您第一次使用--directory运行 MCP 时， uv run通常会在虚拟环境中自动安装它们。
用法
运行服务器
建议使用uv run --directory <path>指向特定 MCP 目录pyproject.toml uv虚拟环境和依赖项。
示例（来自根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数据提取器
提取章节
{
"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_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 服务器
- 为您的 MCP 创建一个新目录（例如，
my_new_mcp ）。 - 在目录内创建：
pyproject.toml ：定义项目元数据、依赖项和脚本入口点（例如， [project.scripts]部分映射my_new_mcp = "my_new_mcp:main" ）。pyrightconfig.json ：（可选）用于类型检查。- 您的主要 Python 文件（例如，
my_new_mcp.py ）：使用mcp库实现 MCP 逻辑（参见下面的模板）。
- 实现所需的类和函数（
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 运行测试：
（确保安装了测试依赖项，可能通过uv pip install pytest或通过将pytest添加到pyproject.toml文件之一中的 dev 依赖项中）。
执照
MIT 许可证
贡献
欢迎贡献代码！欢迎提交 Pull 请求。