Metadata-Version: 2.4
Name: axiom-mcp
Version: 0.1.3
Summary: 🚀 MCP framework that unlocks truly scalable AI systems with zero friction
Author-email: Viraj Shah <viraj.shah1503@gmail.com>
License-File: LICENSE
Keywords: ai,axiom,llm,machine-learning,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.12
Requires-Dist: aiofiles>=23.2.1
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: cachetools>=5.3.2
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: opentelemetry-api>=1.21.0
Requires-Dist: opentelemetry-sdk>=1.21.0
Requires-Dist: pydantic-settings>=2.6.1
Requires-Dist: pydantic<3.0.0,>=2.5.3
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: typer>=0.9.0
Requires-Dist: watchdog>=6.0.0
Provides-Extra: db
Requires-Dist: aioredis>=2.0.1; extra == 'db'
Requires-Dist: asyncpg>=0.29.0; extra == 'db'
Requires-Dist: msgpack>=1.0.7; extra == 'db'
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: build>=1.2.2.post1; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25.3; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: rich>=13.9.4; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=6.1.0; extra == 'dev'
Requires-Dist: watchdog==6.0.0; extra == 'dev'
Provides-Extra: telemetry
Requires-Dist: opentelemetry-instrumentation>=0.42b0; extra == 'telemetry'
Requires-Dist: prometheus-client>=0.19.0; extra == 'telemetry'
Provides-Extra: validation
Requires-Dist: pydantic[email]>=2.5.3; extra == 'validation'
Description-Content-Type: text/markdown

# Axiom MCP

🚀 MCP framework that unlocks truly scalable AI systems with zero friction

## NOTE

This will be oss very soon, working on docs + other misc stuff, if you want
to contribute, send me an email.

## Installation

Using uv (recommended):
```bash
uv pip install axiom-mcp
```

## Development Setup

1. Clone the repository:
   ```bash
   git clone https://github.com/axiomml/axiom-mcp.git
   cd axiom-mcp
   ```

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

3. Create and activate a virtual environment with uv:
   ```bash
   uv venv
   source .venv/bin/activate  # On Unix/Linux
   # or
   .venv\Scripts\activate  # On Windows
   ```

4. Install development dependencies:
   ```bash
   uv pip install -e ".[dev]"
   ```

## Core Features

### 1. Tool Definition

Tools in Axiom MCP are defined as classes that inherit from the `Tool` base class. Here's how to define a tool:

```python
from axiom_mcp.tools.base import Tool, ToolMetadata, ToolValidation

# Define input schema for tool validation
number_input_schema = {
    "type": "object",
    "properties": {
        "a": {"type": "number", "description": "First number"},
        "b": {"type": "number", "description": "Second number"},
    },
    "required": ["a", "b"],
}

class AddTool(Tool):
    """Tool for adding two numbers."""
    metadata = ToolMetadata(
        name="add",
        description="Add two numbers together",
        validation=ToolValidation(input_schema=number_input_schema),
        author="MathServer",
        version="1.0.0",
    )

    async def execute(self, args: Dict[str, Any]) -> Dict[str, Any]:
        a, b = args["a"], args["b"]
        result = a + b
        return {
            "type": "text",
            "content": {"operation": "addition", "a": a, "b": b, "result": result},
        }
```

### 2. Tool Logging and Metrics

Axiom MCP provides comprehensive logging and metrics capabilities for tools:

#### Basic Logging

Each tool has access to a context with built-in logging methods:

```python
class MyTool(Tool):
    async def execute(self, args: Dict[str, Any]) -> Dict[str, Any]:
        # Access logging through tool context
        self.context.debug("Debug level message")
        self.context.info("Processing started")
        self.context.warning("Warning message")
        self.context.error("Error occurred")

        # Your tool logic here
        return result
```

#### Metrics Tracking

The tool manager automatically tracks:
- Total calls
- Successful calls
- Failed calls
- Average execution time
- Last used timestamp

Metrics are stored in the `logs/tools.log` file by default and include:
- Tool name
- Operation status
- Timestamp
- Execution time
- Error messages (if any)

#### Advanced Features

1. **Cache Control**:
```python
# Disable caching for specific execution
tool_context = ToolContext(cache_enabled=False)
tool = MyTool(context=tool_context)
```

2. **Execution Timeout**:
```python
# Set custom timeout
tool_context = ToolContext(timeout=30.0)  # 30 seconds
```

3. **Dry Run Mode**:
```python
# Enable dry run for testing
tool_context = ToolContext(dry_run=True)
```

### 3. Resource Definition

Resources are lightweight endpoints that can be defined using decorators:

```python
from pathlib import Path
from axiom_mcp import AxiomMCP

mcp = AxiomMCP("MyServer", port=8888)

# Simple string resource
@mcp.resource("greeting://{name}")
def say_hello(name: str) -> str:
    return f"Hello, {name}!"

# Resource returning a list of files
@mcp.resource("dir://desktop")
def list_files() -> list[str]:
    desktop = Path.home() / "Documents"
    return [str(f) for f in desktop.iterdir()]
```

## Running the Server

```python
axiom-mcp dev server.py # This runs in dev mode
axiom-mcp run server.py # This runs in release/prod mode
```

## Development Commands

```bash
# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=axiom_mcp tests/

# Update dependencies
uv pip compile pyproject.toml -o requirements.txt

# Sync your environment
uv pip sync requirements.txt
```

## Contributing

1. Fork the repository
2. Create a new branch for your feature
3. Make your changes
4. Run the tests:
   ```bash
   uv run pytest
   ```
5. Submit a pull request

## License
GNU General Public License v3 (GPLv3)
