AI Tool Infrastructure

A Python library for quickly creating MCP (Model Context Protocol) servers with enterprise features like audit logging, policy enforcement, and state management.

Quick Start

Create an MCP server in under 30 lines:

from ai_tool_infra import (
    ExecutionEngine, ToolRegistry, PolicyEngine,
    AuditLog, StateManager, tool,
)
from ai_tool_infra.adapters.mcp import MCPAdapter, create_mcp_server

# Define a tool
@tool(name="greet", description="Greet a user")
async def greet(name: str) -> str:
    return f"Hello, {name}!"

# Build infrastructure
registry = ToolRegistry()
engine = ExecutionEngine(registry, PolicyEngine(), AuditLog(), StateManager())
registry.register(greet)

# Create and run MCP server
adapter = MCPAdapter(engine, registry)
mcp = create_mcp_server(adapter, "my-server")
mcp.run(transport="sse", host="0.0.0.0", port=8000)

Installation

# Using uv
uv add ai-tool-infra

# With server dependencies
uv add "ai-tool-infra[server]"

# For development
uv add "ai-tool-infra[dev]"

Architecture

AI Tool Infrastructure
├── Core Layer
│   ├── ToolContract      # Define tool behavior, side effects, costs
│   ├── ToolRegistry      # Register and discover tools
│   ├── ExecutionEngine   # Execute tools with policy/audit/state
│   ├── AuditLog          # Track all tool executions
│   └── StateManager      # Manage execution state
├── Auth Layer
│   └── PolicyEngine      # RBAC, permissions, rate limits
├── Adapters
│   ├── MCPAdapter        # Expose tools via MCP protocol
│   └── RESTAdapter       # Expose tools via REST API
└── Connectors
    ├── BaseConnector     # Base class for API connectors
    └── KruncherConnector # Example: Kruncher API connector

Features

Tool Contracts

Define tools with rich metadata:

from ai_tool_infra import ToolContract, SideEffect, CostHint

tool = ToolContract(
    name="create_user",
    description="Create a new user",
    input_schema={...},
    handler=create_user_handler,
    side_effect=SideEffect.WRITE,      # Declares write operation
    idempotent=False,                  # Not safe to retry
    cost_hint=CostHint.EXPENSIVE,      # Requires confirmation
    required_permissions=["users:write"],
    tags=["users", "write"],
)

Custom Connectors

Create connectors for any API:

from ai_tool_infra.connectors.base import BaseConnector, ConnectorConfig

class MyAPIConnector(BaseConnector):
    async def health_check(self) -> ConnectorHealth:
        return ConnectorHealth(healthy=True, message="OK")

    def get_tools(self) -> list[ToolContract]:
        return [
            ToolContract(name="my_tool", handler=self._my_handler, ...),
        ]

    async def _my_handler(self, **kwargs) -> dict:
        return {"result": "success"}

Policy Enforcement

Control access with RBAC:

from ai_tool_infra import PolicyEngine, PolicyRule, User, Role

policy = PolicyEngine()
policy.add_rule(PolicyRule(
    permissions=["projects:write"],
    roles=[Role.ADMIN, Role.EDITOR],
))

Project Structure

ai-tool-infra/
├── ai_tool_infra/           # Main library
│   ├── adapters/            # Protocol adapters (MCP, REST)
│   ├── auth/                # Authentication & authorization
│   ├── connectors/          # API connectors
│   ├── core/                # Core infrastructure
│   └── utils/               # Utilities
├── examples/                # Example scripts
│   ├── quick_start.py       # Minimal example
│   ├── demo_server.py       # Full Kruncher demo
│   └── custom_connector.py  # Custom connector example
├── tests/                   # Test suite
└── pyproject.toml

Examples

Run Quick Start

uv run python examples/quick_start.py

Run Kruncher Demo

# Set environment variables
export KRUNCHER_API_KEY=your_api_key

# Run server
uv run python examples/demo_server.py

Run Custom Connector Example

uv run python examples/custom_connector.py

Connecting to ChatGPT

1. Start the MCP server (e.g., uv run python examples/demo_server.py)
2. Expose via ngrok: ngrok http 8000
3. In ChatGPT: Settings → Connectors → Add Connector
4. Enter the ngrok URL: https://your-url.ngrok.io/sse

Environment Variables

# Required for Kruncher connector
KRUNCHER_API_KEY=your_api_key
KRUNCHER_API_URL=https://api.kruncher.ai/api/integration/project

# Server configuration
HOST=0.0.0.0
PORT=8000

# Optional
LOG_LEVEL=INFO

Resources

• MCP Protocol Documentation
• FastMCP Documentation
• ChatGPT MCP Integration