Add aden-tools: FastMCP server with core tools

Author: bryanadenhq

aden-tools/BUILDING_TOOLS.md

@@ -0,0 +1,194 @@
+# Building Tools for Aden
+
+This guide explains how to create new tools for the Aden agent framework.
+
+## Quick Start Checklist
+
+1. Create folder under `src/aden_tools/tools/<tool_name>/`
+2. Implement class extending `BaseTool` with `args_schema`
+3. Declare `env_vars` if your tool needs environment variables
+4. Implement `_run()` and optionally `_arun()` for async
+5. Add a `README.md` documenting your tool
+6. Export from `src/aden_tools/tools/__init__.py`
+7. Add tests in `tests/tools/`
+
+## Tool Structure
+
+Each tool lives in its own folder:
+
+```
+src/aden_tools/tools/my_tool/
+├── __init__.py           # Export the tool class
+├── my_tool.py            # Tool implementation
+└── README.md             # Documentation
+```
+
+## Implementation Pattern
+
+### 1. Define Input Schema
+
+Use Pydantic to define your tool's input parameters:
+
+```python
+from pydantic import BaseModel, Field
+
+class MyToolSchema(BaseModel):
+    """Input schema for MyTool."""
+
+    query: str = Field(
+        ...,  # Required
+        description="The search query",
+        min_length=1,
+        max_length=500,
+    )
+    limit: int = Field(
+        default=10,
+        description="Maximum number of results",
+        ge=1,
+        le=100,
+    )
+```
+
+### 2. Implement the Tool Class
+
+```python
+from aden_tools import BaseTool, EnvVar
+
+class MyTool(BaseTool):
+    name: str = "my_tool"
+    description: str = (
+        "Searches for items matching a query. "
+        "Use this when you need to find specific information."
+    )
+    args_schema: type[BaseModel] = MyToolSchema
+
+    # Optional: declare required environment variables
+    env_vars: list[EnvVar] = [
+        EnvVar(
+            name="MY_API_KEY",
+            description="API key for the service",
+            required=True,
+        ),
+    ]
+
+    def _run(self, query: str, limit: int = 10, **kwargs) -> str:
+        """Execute the tool."""
+        try:
+            # Your implementation here
+            results = self._search(query, limit)
+            return f"Found {len(results)} results"
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    async def _arun(self, query: str, limit: int = 10, **kwargs) -> str:
+        """Async version (optional)."""
+        # Async implementation
+        pass
+```
+
+### 3. Export the Tool
+
+In `src/aden_tools/tools/my_tool/__init__.py`:
+```python
+from .my_tool import MyTool, MyToolSchema
+
+__all__ = ["MyTool", "MyToolSchema"]
+```
+
+In `src/aden_tools/tools/__init__.py`:
+```python
+from .my_tool import MyTool, MyToolSchema
+
+__all__ = [
+    # ... existing tools
+    "MyTool",
+    "MyToolSchema",
+]
+```
+
+## Required Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | str | Unique identifier (snake_case) |
+| `description` | str | What the tool does and when to use it |
+| `args_schema` | type[BaseModel] | Pydantic model for input validation |
+
+## Optional Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `env_vars` | list[EnvVar] | [] | Required environment variables |
+| `max_usage_count` | int \| None | None | Limit tool usage |
+| `result_as_answer` | bool | False | Use result as final answer |
+| `cache_function` | Callable | None | Caching logic |
+
+## Best Practices
+
+### Error Handling
+
+Return helpful error messages instead of raising exceptions:
+
+```python
+def _run(self, **kwargs) -> str:
+    try:
+        result = self._do_work()
+        return result
+    except SpecificError as e:
+        return f"Failed to process: {str(e)}"
+    except Exception as e:
+        return f"Unexpected error: {str(e)}"
+```
+
+### Environment Variables
+
+Validate credentials early in `__init__` if needed:
+
+```python
+def __init__(self, **kwargs):
+    super().__init__(**kwargs)
+    from aden_tools import validate_env_vars
+    self._env = validate_env_vars(self.env_vars)
+```
+
+### Return Values
+
+- Return strings for simple results
+- Return dicts for structured data (will be JSON-serialized)
+- Keep output concise and deterministic
+
+### Documentation
+
+Every tool needs a `README.md` with:
+- Description and use cases
+- Usage examples
+- Argument table
+- Environment variables (if any)
+- Error handling notes
+
+## Testing
+
+Place tests in `tests/tools/test_my_tool.py`:
+
+```python
+import pytest
+from aden_tools.tools import MyTool
+
+def test_my_tool_basic():
+    tool = MyTool()
+    result = tool.run(query="test")
+    assert "results" in result
+
+def test_my_tool_validation():
+    tool = MyTool()
+    with pytest.raises(ValueError):
+        tool.run(query="")  # Empty query should fail
+```
+
+Mock external APIs to keep tests fast and deterministic.
+
+## Naming Conventions
+
+- **Folder name**: `snake_case` (e.g., `file_read_tool`)
+- **Class name**: `PascalCase` ending in `Tool` (e.g., `FileReadTool`)
+- **Tool name attribute**: `snake_case` (e.g., `file_read`)

aden-tools/Dockerfile

@@ -0,0 +1,29 @@
+# Aden Tools MCP Server
+# Exposes aden-tools via Model Context Protocol
+
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Copy project files
+COPY pyproject.toml ./
+COPY README.md ./
+COPY src ./src
+COPY mcp_server.py ./
+
+# Install package with all dependencies
+RUN pip install --no-cache-dir -e .
+
+# Create non-root user for security
+RUN useradd -m -u 1001 appuser && chown -R appuser:appuser /app
+USER appuser
+
+# Expose MCP server port
+EXPOSE 4001
+
+# Health check - verify server is responding
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD python -c "import httpx; httpx.get('http://localhost:4001/health').raise_for_status()" || exit 1
+
+# Run MCP server with HTTP transport
+CMD ["python", "mcp_server.py"]

aden-tools/README.md

@@ -0,0 +1,79 @@
+# Aden Tools
+
+Tool library for the Aden agent framework. Provides a collection of tools that AI agents can use to interact with external systems, process data, and perform actions.
+
+## Installation
+
+```bash
+pip install -e aden-tools
+```
+
+For development:
+```bash
+pip install -e "aden-tools[dev]"
+```
+
+## Quick Start
+
+```python
+from aden_tools import ExampleTool
+
+# Create and use a tool
+tool = ExampleTool()
+result = tool.run(message="Hello World", uppercase=True)
+print(result)  # "HELLO WORLD"
+```
+
+## Creating Custom Tools
+
+```python
+from pydantic import BaseModel, Field
+from aden_tools import BaseTool
+
+class MyToolSchema(BaseModel):
+    """Input schema for MyTool."""
+    query: str = Field(..., description="The search query")
+    limit: int = Field(default=10, description="Max results")
+
+class MyTool(BaseTool):
+    name: str = "my_tool"
+    description: str = "Searches for items matching the query"
+    args_schema: type[BaseModel] = MyToolSchema
+
+    def _run(self, query: str, limit: int = 10, **kwargs) -> str:
+        # Your tool logic here
+        return f"Found {limit} results for: {query}"
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `ExampleTool` | Template tool demonstrating the pattern |
+
+## Project Structure
+
+```
+aden-tools/
+├── src/aden_tools/
+│   ├── __init__.py          # Main exports
+│   ├── base_tool.py         # BaseTool class
+│   ├── tool_types.py        # Type definitions
+│   ├── adapters/            # Framework adapters
+│   ├── utils/               # Utility functions
+│   └── tools/               # Tool implementations
+│       └── example_tool/    # Example tool
+├── tests/                   # Test suite
+├── README.md
+├── BUILDING_TOOLS.md        # Tool development guide
+└── pyproject.toml
+```
+
+## Documentation
+
+- [Building Tools Guide](BUILDING_TOOLS.md) - How to create new tools
+- Individual tool READMEs in `src/aden_tools/tools/*/README.md`
+
+## License
+
+MIT

aden-tools/mcp_server.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""
+Aden Tools MCP Server
+
+Exposes all aden-tools via Model Context Protocol using FastMCP.
+
+Usage:
+    # Run with HTTP transport (default, for Docker)
+    python mcp_server.py
+
+    # Run with custom port
+    python mcp_server.py --port 8001
+
+    # Run with STDIO transport (for local testing)
+    python mcp_server.py --stdio
+
+Environment Variables:
+    MCP_PORT              - Server port (default: 4001)
+    BRAVE_SEARCH_API_KEY  - Required for web_search tool
+"""
+import argparse
+import os
+
+from fastmcp import FastMCP
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+mcp = FastMCP("aden-tools")
+
+# Register all tools with the MCP server
+from aden_tools.tools import register_all_tools
+
+tools = register_all_tools(mcp)
+print(f"[MCP] Registered {len(tools)} tools: {tools}")
+
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request: Request) -> PlainTextResponse:
+    """Health check endpoint for container orchestration."""
+    return PlainTextResponse("OK")
+
+
+@mcp.custom_route("/", methods=["GET"])
+async def index(request: Request) -> PlainTextResponse:
+    """Landing page for browser visits."""
+    return PlainTextResponse("Welcome to the Hive MCP Server")
+
+
+def main() -> None:
+    """Entry point for the MCP server."""
+    parser = argparse.ArgumentParser(description="Aden Tools MCP Server")
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.getenv("MCP_PORT", "4001")),
+        help="HTTP server port (default: 4001)",
+    )
+    parser.add_argument(
+        "--host",
+        default="0.0.0.0",
+        help="HTTP server host (default: 0.0.0.0)",
+    )
+    parser.add_argument(
+        "--stdio",
+        action="store_true",
+        help="Use STDIO transport instead of HTTP",
+    )
+    args = parser.parse_args()
+
+    if args.stdio:
+        print("[MCP] Starting with STDIO transport")
+        mcp.run(transport="stdio")
+    else:
+        print(f"[MCP] Starting HTTP server on {args.host}:{args.port}")
+        mcp.run(transport="http", host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()