README.md•3.77 kB
# 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:
```bash
# 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:
```bash
just build
```
## Usage
### Running the MCP Server
To start the MCP agents server:
```bash
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:
```json
{
"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:
```json
{
"mcpServers": {
"mcp-agents": {
"command": "uvx",
"args": ["amajakai14_mcp-agents"]
}
}
}
```
Alternative with `pipx`:
```json
{
"mcpServers": {
"mcp-agents": {
"command": "pipx",
"args": ["run", "amajakai14_mcp-agents"]
}
}
}
```
#### Option 3: Version Pinning
To pin to a specific version:
```json
{
"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:
```bash
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:**
```json
{
"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:
```python
@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
```bash
just test
```
## License
MIT License