"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 } }

"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 ] } }

"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 ] } }

"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" } } }

"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 } } }

# 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

{ "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" } ] }

{ "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": "/path/to/template.docx" }

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

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

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

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 tests/