duck-mcp by theddnc - MCP Server

Duck MCP Server 🦆

A simple MCP (Model Context Protocol) server built with FastMCP.

Features

This server provides the following tools:

select_option: Ask user to select one option from provided choices (uses elicitation)
provide_information: Request additional information from user in natural language (uses elicitation)
request_manual_test: Request the user to perform manual testing and report results (uses elicitation)

Installation

Prerequisites

Python 3.10 or higher
uv (recommended) or pip

Install Dependencies

Using uv (recommended):

uv sync

Using pip:

pip install -e .

Usage

Running the Server

Using the FastMCP CLI (recommended):

# Run with default configuration from fastmcp.json
fastmcp run

# Or specify the config file explicitly
fastmcp run fastmcp.json

# Run with HTTP transport for testing
fastmcp run --transport http --port 8000

Using Python directly:

python server.py

Running with uv:

uv run fastmcp run server.py

Development Mode

Run with the FastMCP Inspector UI:

fastmcp dev

Inspect Server Capabilities

View all available tools, resources, and prompts:

fastmcp inspect

Installing to MCP Clients

Claude Desktop

fastmcp install claude-desktop

Cursor

fastmcp install cursor

Claude Code (VS Code Extension)

fastmcp install claude-code

Testing

You can test the server using a FastMCP client:

import asyncio
from fastmcp import Client

async def test_server():
    async with Client("http://localhost:8000/mcp") as client:
        # Ping the server to check connectivity
        await client.ping()
        print("Server is running!")

if __name__ == "__main__":
    asyncio.run(test_server())

Testing Elicitation Tools

The select_option, provide_information, and request_manual_test tools use FastMCP's elicitation feature to interactively request information from users:

import asyncio
from fastmcp import Client

async def elicitation_handler(message: str, response_type: type, params, context):
    """Handler that responds to server's elicitation requests"""
    print(f"Server asks: {message}")
    user_input = input("Your response: ")
    return response_type(selected_option=user_input) if hasattr(response_type, '__annotations__') and 'selected_option' in response_type.__annotations__ else response_type(information=user_input)

async def test_elicitation():
    async with Client("http://localhost:8000/mcp", elicitation_handler=elicitation_handler) as client:
        # Test select_option tool
        result = await client.call_tool("select_option", {
            "question": "What's your favorite programming language?",
            "options": ["Python", "JavaScript", "Rust", "Go"]
        })
        print(result.data)
        
        # Test provide_information tool
        result = await client.call_tool("provide_information", {
            "question": "What would you like to build today?"
        })
        print(result.data)
        
        # Test request_manual_test tool
        result = await client.call_tool("request_manual_test", {
            "test_description": "Navigate to the login page and verify the form renders correctly",
            "expected_outcome": "Login form should display username/password fields and submit button"
        })
        print(result.data)

if __name__ == "__main__":
    asyncio.run(test_elicitation())

Project Structure

duck-mcp/
├── server.py          # Main server implementation
├── fastmcp.json       # FastMCP configuration
├── pyproject.toml     # Project metadata and dependencies
├── README.md          # This file
└── tests/            # Test files (optional)

Development

Adding New Tools

To add a new tool to the server, simply decorate a function with @mcp.tool:

@mcp.tool
def my_new_tool(arg1: str, arg2: int) -> str:
    """Description of what this tool does"""
    # Your implementation here
    return "result"

Running Tests

pytest

Deployment

Local Deployment

The server runs with stdio transport by default, making it compatible with local MCP clients like Claude Desktop.

HTTP Deployment

For remote access, run with HTTP transport:

fastmcp run --transport http --host 0.0.0.0 --port 8000

FastMCP Cloud

Deploy to FastMCP Cloud for managed hosting (requires account):

fastmcp cloud deploy

Configuration

The fastmcp.json file contains the server configuration:

source: Location and entrypoint of the server code
environment: Python version and dependencies
deployment: Runtime configuration (transport, logging, etc.)

You can override any configuration via CLI arguments:

fastmcp run --port 8080 --log-level DEBUG

MCP Client Configuration

To use this MCP server with MCP-compatible clients (like Claude Desktop), add the following configuration to your client's mcp.json file:

Using uv (recommended):

{
  "mcpServers": {
    "duck-mcp": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "server.py"],
      "cwd": "/path/to/duck-mcp"
    }
  }
}

Using Python directly:

{
  "mcpServers": {
    "duck-mcp": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/duck-mcp"
    }
  }
}

Replace /path/to/duck-mcp with the actual path to your duck-mcp directory. The cwd (current working directory) ensures the server runs from the correct location.

Learn More

License

MIT