automagik-tools 0.1.1

A monorepo package for MCP tools with dynamic loading capabilities

automagik-tools

🚀 The Premier Repository for Model Context Protocol (MCP) Tools

A self-discovering, zero-configuration monorepo for MCP tools. Just drop your tool in the tools/ directory and it's automatically available - no registration needed!

✨ Key Features:

• 🔍 Auto-Discovery - Tools are found automatically, no manual registration
• 📦 Self-Contained - Each tool is completely independent
• 🚀 Zero Config - Just add your tool folder and it works
• 🛠️ FastMCP Powered - Built on the robust FastMCP framework
• 🎯 5-Minute Setup - Add a new tool in minutes, not hours

Our Vision: To become the largest and most comprehensive collection of MCP tools, making it trivially easy for developers to add new integrations and for users to discover and use them.

---

🚀 Features

🎯 For Tool Developers

• Zero Registration - Just create a folder in tools/ and it's discovered
• Self-Contained Tools - Each tool is independent with its own config
• Auto-Discovery - The hub automatically finds and mounts all tools
• FastMCP Compliant - Built on FastMCP with proper patterns
• 5-Minute Setup - Add a new tool faster than making coffee

🛠️ For Tool Users

• One Command - make fastmcp-hub runs everything
• Multi-tool Server - All tools available on one server
• Dynamic Loading - Tools are discovered and loaded at runtime
• CLI Interface - List, run, and manage tools easily
• Type-Safe Config - Pydantic-based settings with environment variables

---

📦 Installation

Option 1: Using uvx (Recommended)

The easiest way to use automagik-tools is with uvx, which runs the tool in an isolated environment without affecting your system Python:

# Run directly without installation
uvx automagik-tools --help

# List available tools
uvx automagik-tools list

# Run a server
uvx automagik-tools serve-all --tools evolution-api

Option 2: Using pip

You can also install automagik-tools as a standard Python package:

# Install globally or in a virtual environment
pip install automagik-tools

# Or install the latest development version
pip install git+https://github.com/namastexlabs/automagik-tools.git

Option 3: Development Installation

For development, we use uv for dependency management:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/namastexlabs/automagik-tools.git
cd automagik-tools
uv sync --all-extras

# Run commands with uv
uv run automagik-tools list
uv run pytest

---

🏁 Quick Start

1. List Available Tools

# Using uvx (recommended)
uvx automagik-tools list

# Or using pip-installed version
automagik-tools list

2. Run a Tool Server (Single Tool)

# Using uvx
uvx automagik-tools serve --tool evolution-api

# Or using pip-installed version
automagik-tools serve --tool evolution-api

• By default, serves on 0.0.0.0:8000 (configurable with --host and --port)
• The tool will be available at /mcp (e.g., http://localhost:8000/mcp)

3. Run a Multi-Tool Server

# Using uvx
uvx automagik-tools serve-all --tools evolution-api

# Or using pip-installed version  
automagik-tools serve-all --tools evolution-api,discord,notion

• Each tool is mounted at its own path, e.g., /evolution-api/mcp, /discord/mcp
• You can specify which tools to serve with --tools, or omit to serve all discovered tools

🤖 Connecting to MCP-Compatible Clients

You can connect your automagik-tools server to any MCP-compatible client in several ways:

Option 1: Using uvx with stdio transport (Recommended)

Most MCP clients support running tools via stdio transport using uvx:

{
  "mcpServers": {
    "automagik-tools": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["automagik-tools", "serve", "--tool", "evolution-api", "--transport", "stdio"],
      "env": {
        "EVOLUTION_API_BASE_URL": "https://your-api-server.com",
        "EVOLUTION_API_KEY": "your_api_key_here"
      }
    }
  }
}

For multiple tools:

{
  "mcpServers": {
    "automagik-tools-multi": {
      "transport": "stdio",
      "command": "uvx", 
      "args": ["automagik-tools", "serve-all", "--tools", "evolution-api", "--transport", "stdio"],
      "env": {
        "EVOLUTION_API_BASE_URL": "https://your-api-server.com",
        "EVOLUTION_API_KEY": "your_api_key_here"
      }
    }
  }
}

Option 2: Using uvx with development version

If you're developing or want to use a local version:

{
  "mcpServers": {
    "automagik-tools-dev": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["--from", "/path/to/automagik-tools", "automagik-tools", "serve", "--tool", "evolution-api", "--transport", "stdio"],
      "env": {
        "EVOLUTION_API_BASE_URL": "https://your-api-server.com",
        "EVOLUTION_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Desktop Example

For Claude Desktop, add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "automagik-tools": {
      "command": "uvx",
      "args": ["automagik-tools", "serve", "--tool", "evolution-api", "--transport", "stdio"],
      "env": {
        "EVOLUTION_API_BASE_URL": "https://your-api-server.com",
        "EVOLUTION_API_KEY": "your_api_key_here"
      }
    }
  }
}

This allows your LLM agent or automation platform to call tools, access resources, and use prompts exposed by automagik-tools as part of its workflow.

💡 Why uvx?

• No installation required: Run automagik-tools without installing it globally
• Isolated environment: Each run uses a fresh, isolated Python environment
• Always latest: Automatically pulls the latest version from PyPI
• No conflicts: Doesn't interfere with your system Python or other tools
• Zero setup: Works immediately if you have uv installed

---

⚙️ Configuration

Tools use environment variables for configuration. Copy .env.example to .env and fill in your values:

cp .env.example .env
# Edit .env with your API keys and settings

Each tool has its own configuration prefix:

# Evolution API (WhatsApp)
EVOLUTION_API_BASE_URL=https://your-evolution-api-server.com
EVOLUTION_API_KEY=your_api_key_here
EVOLUTION_API_TIMEOUT=30

# Future tools follow the same pattern
# GITHUB_API_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
# DISCORD_BOT_TOKEN=your-bot-token
# NOTION_API_KEY=secret_xxxxxxxxxxxxxxxxxxxx

See .env.example for all available configuration options.

---

🪄 Adding a New Tool (5 Minutes!)

No registration needed! Just create your tool and it's automatically discovered.

Super Quick Start

1. Create your tool folder:

mkdir -p automagik_tools/tools/my_tool

2. Add required files (see Tool Development Guide):

   • __init__.py - Your tool implementation with 3 required functions
   • config.py - Pydantic configuration class
   • __main__.py - Standalone runner (optional)
   • README.md - Documentation (optional)

3. That's it! Your tool is now:

   • ✅ Auto-discovered by the hub
   • ✅ Available in all commands
   • ✅ Ready to use

Example Tool Structure

# automagik_tools/tools/my_tool/__init__.py
def get_metadata():
    return {"name": "my-tool", "version": "1.0.0", "description": "My awesome tool"}

def get_config_class():
    return MyToolConfig

def create_server(config=None):
    # Create your FastMCP server here
    pass

Try it: Run make fastmcp-hub and your tool is automatically mounted!

---

🛠️ Developing New Tools

Quick Start: Create a New Tool

The easiest way to create a new tool is using our interactive tool generator:

# Interactive mode (recommended)
python scripts/create_tool.py

# Or with parameters
python scripts/create_tool.py --name "GitHub API" --description "GitHub integration for MCP"

This will:

1. Create the tool directory structure
2. Generate boilerplate code from templates
3. Set up tests
4. Update configuration files
5. Register the tool in pyproject.toml

Manual Tool Creation

For more control, see our comprehensive Tool Creation Guide which includes:

• Step-by-step instructions
• Common patterns (REST APIs, WebSockets, databases)
• Testing strategies
• Best practices
• Example implementations

Available Tool Templates

• Basic Tool: Minimal MCP tool structure
• REST API Tool: HTTP client with authentication
• WebSocket Tool: Real-time communication
• Database Tool: SQL/NoSQL integrations
• File System Tool: Local file operations

Example: Hello World Tool

See automagik_tools/tools/example_hello/ for a minimal working example that demonstrates:

• Basic tool structure
• Multiple tool methods
• Resources and prompts
• Proper testing patterns

---

🧩 Contributing

Adding a New Tool

1. Use the tool generator: python scripts/create_tool.py
2. Implement your tool logic: Follow the patterns in existing tools
3. Add tests: Use the generated test template
4. Update documentation: Add your tool to this README
5. Submit a PR: We welcome all contributions!

Tool Ideas We'd Love to See

• Communication: Discord, Slack, Telegram, Email
• Productivity: Notion, Google Workspace, Microsoft 365, Todoist
• Development: GitHub, GitLab, Jira, Docker, Kubernetes
• AI/ML: OpenAI, Anthropic, Hugging Face, Replicate
• Data: PostgreSQL, Redis, Elasticsearch, S3
• Monitoring: Datadog, Sentry, Prometheus
• Finance: Stripe, PayPal, Crypto APIs
• IoT: Home Assistant, MQTT, Arduino

See docs/TOOL_CREATION_GUIDE.md for detailed contribution guidelines.

---

📚 Documentation

• Tool Creation Guide - Comprehensive guide for building new tools
• FastMCP Documentation - MCP framework documentation
• MCP Specification - Model Context Protocol specification
• API Reference - Detailed API documentation (coming soon)

Available Tools

Tool	Description	Status
evolution-api	WhatsApp integration via Evolution API	✅ Ready
example-hello	Simple example tool for learning	✅ Ready
discord	Discord bot integration	🚧 Planned
notion	Notion workspace integration	🚧 Planned
github	GitHub API integration	🚧 Planned
openai	OpenAI API integration	🚧 Planned

Want to add a tool? Check our contribution guide!

---

📝 License

MIT

---

🧪 Testing

The project includes a comprehensive test suite using pytest. After installation, you can run tests directly:

Quick Test Commands

# Install development dependencies first
uv pip install -e ".[dev]"

# Run all tests
pytest tests/

# Run specific test categories
pytest tests/test_cli.py              # CLI tests
pytest tests/test_mcp_protocol.py     # MCP protocol tests  
pytest tests/test_integration.py      # Integration tests
pytest tests/tools/                   # Tool-specific tests

# Run tests with coverage
pytest tests/ --cov=automagik_tools --cov-report=html

# Run specific test
pytest tests/test_cli.py::TestCLIBasics::test_list_command -v

# Run tests matching a pattern
pytest -k "test_list" -v

# Skip slow tests
pytest tests/ -m "not slow" -v

Using Make (Alternative)

We also provide a Makefile for convenience:

make help           # Show all available commands
make test           # Run all tests  
make test-unit      # Run unit tests
make test-mcp       # Run MCP protocol tests
make test-coverage  # Run with coverage report
make lint           # Check code quality
make format         # Format code

Test Categories

The test suite is organized into several categories:

• Unit Tests (test_cli.py, test_evolution_api.py): Test individual components
• MCP Protocol Tests (test_mcp_protocol.py): Test MCP compliance and stdio transport
• Integration Tests (test_integration.py): Test complete workflows end-to-end

Environment Variables for Testing

Set these environment variables for Evolution API tests:

export EVOLUTION_API_BASE_URL="http://your-api-server:8080"
export EVOLUTION_API_KEY="your_api_key"

Test Configuration

Tests are configured via pytest.ini. Key features:

• Automatic async support for MCP protocol testing
• Coverage reporting with HTML output in htmlcov/
• Test markers for categorizing tests (unit, integration, mcp, etc.)
• Timeout protection for long-running tests

---