MCP Agents - Example FastMCP Server

A simple Model Context Protocol (MCP) server built with FastMCP that demonstrates basic tool implementation.

Features

• greet: Greet a user by name

Installation

This project uses uv for package management and just for task running. Make sure you have both installed:

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install just if you don't have it
# On macOS with Homebrew:
brew install just
# Or with cargo:
cargo install just

Then build the project:

just build

Usage

Running the MCP Server

To start the MCP agents server:

just run

Using with MCP Clients

You can use this server with any MCP-compatible client. The configuration depends on how you want to run the server:

Option 1: Local Development (using source code)

For development or when running from a local clone:

{
  "mcpServers": {
    "mcp-agents": {
      "command": "uv",
      "args": ["run", "mcp-agents"],
      "cwd": "/Users/means/repository/mcp-agents",
      "env": {}
    }
  }
}

Option 2: PyPI Installation (recommended for end users)

Once published to PyPI, users can use this simpler configuration:

{
  "mcpServers": {
    "mcp-agents": {
      "command": "uvx",
      "args": ["amajakai14_mcp-agents"]
    }
  }
}

Alternative with pipx:

{
  "mcpServers": {
    "mcp-agents": {
      "command": "pipx",
      "args": ["run", "amajakai14_mcp-agents"]
    }
  }
}

Option 3: Version Pinning

To pin to a specific version:

{
  "mcpServers": {
    "mcp-agents": {
      "command": "uvx",
      "args": ["amajakai14_mcp-agents==0.1.0"]
    }
  }
}

For Claude Desktop

Add any of the above configurations to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Testing the Tools

Run the test script to verify the tools work correctly:

just test

Available Tools

greet

Greets a user by name.

Parameters:

• name (string): The name of the person to greet

Returns: A friendly greeting message.

Example:

{
  "name": "greet",
  "arguments": {
    "name": "Alice"
  }
}

Response:

"Hello, Alice!"

Development

Available Just Commands

• just build - Install dependencies and sync the project
• just run - Start the MCP agents server
• just test - Run the test script
• just format - Format code with black and isort
• just typecheck - Run type checking with mypy
• just dev - Install development dependencies
• just dist - Build distribution packages
• just clean - Clean build artifacts
• just publish - Publish to PyPI (used in CI)

Project Structure

mcp-agents/
├── src/
│   └── agents/
│       └── __init__.py          # Main MCP server implementation
├── pyproject.toml               # Project configuration and dependencies
├── justfile                     # Task runner configuration
├── mcp_config.json             # MCP client configuration example
├── test_tools.py               # Simple test script
└── README.md                   # This file

Adding New Tools

To add new tools using FastMCP:

1. Add a new function with the @mcp.tool() decorator:

   @mcp.tool("tool_name", description="Description of what the tool does")
   def tool_name(param1: type, param2: type) -> return_type:
       # Tool implementation
       return result
   

2. Update the README with documentation for the new tool

Running Tests

just test

License

MIT License