使用说明
有用的模型上下文协议服务器（MCPS）
一组实现模型上下文协议的独立Python脚本 用于各种实用功能的（MCP）服务器。每台服务器都提供专业 AI助手或其他支持 MCP协议。
什么是MCP？
模型上下文协议（MCP）是人工智能助手的一种标准化方式 与外部工具和服务交互。它允许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服务器渲染PlantUML图的服务器（通常通过 Docker）。
工具：
- 渲染图：将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)
一个使用mercurchart.com API绘制人鱼图的服务器。
工具：
- 渲染美人鱼图表：通过创建一个PNG图像将Mermaid代码转换为PNG图像 mermaidchart.com上的文件。
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
}
}
}
安装
-
克隆存储库：
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 -
依赖关系： 依赖关系由MCP通过以下方式管理
pyproject.toml.uv run通常会在虚拟环境中自动安装它们 首次使用以下命令运行MCP时的环境--directory.
用法
运行服务器
建议使用以下命令运行每个MCP服务器 uv run --directory <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客户端应用程序以启动所需的服务器
command 和 args “MCP服务器配置”示例中所示的结构
对于每台服务器。确保 command 指向您的 uv 可执行文件和
args 正确指定 --directory 带有MCP文件夹的路径和
要运行的脚本名称。使用传递必要的环境变量（如API令牌）
这 env 财产。
工具特定使用示例
这些显示了示例 arguments 您将发送至 call_tool 功能
相应的MCP服务器。
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运行测试：
pytest tests/
（确保安装了测试依赖项，可能是通过
uv pip install pytest 或通过添加 pytest 到其中一个中的开发依赖项
这 pyproject.toml 文件）。
许可证
贡献
欢迎投稿！请随时提交拉取请求。
