Metadata-Version: 2.4
Name: toolatlas-mcp
Version: 0.1.0
Summary: ToolAtlas — Discover, Govern, and Optimize MCP Tools
Author: ToolAtlas contributors
License: MIT
Project-URL: Homepage, https://github.com/anomalyco/toolatlas-mcp
Project-URL: Repository, https://github.com/anomalyco/toolatlas-mcp
Project-URL: Issues, https://github.com/anomalyco/toolatlas-mcp/issues
Keywords: mcp,model-context-protocol,tools,governance,proxy,registry,ai,llm,agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: sqlalchemy[asyncio]>=2.0
Requires-Dist: aiosqlite>=0.20
Requires-Dist: httpx>=0.27
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.0
Requires-Dist: sse-starlette>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Dynamic: license-file

# ToolAtlas-MCP

**The Control Plane for Your MCP Tools**

[![PyPI version](https://img.shields.io/pypi/v/toolatlas-mcp)](https://pypi.org/project/toolatlas-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/toolatlas-mcp)](https://pypi.org/project/toolatlas-mcp/)
[![License](https://img.shields.io/pypi/l/toolatlas-mcp)](LICENSE)

ToolAtlas sits between AI clients and MCP servers — giving you a **central registry**, **intelligent proxy**, **per-tool governance**, **usage analytics**, and a **beautiful web dashboard**.

```
pip install toolatlas-mcp
toolatlas start
# → http://localhost:8080
```

---

## Why ToolAtlas?

MCP (Model Context Protocol) is exploding. Teams run 5, 10, 50 MCP servers — GitHub, Jira, Slack, Confluence, databases, APIs. Each exposes tools your AI agents can call. ToolAtlas is the missing layer that helps you **see everything, control what matters, and understand usage**.

---

## Features

### 🔌 Universal MCP Proxy
Connect any number of MCP servers and expose them through a single proxy endpoint. Group tools by team, project, or purpose using **proxies** — each with its own tool set and settings.

### 🛡️ Per-Tool Governance
- **Enable/disable** tools per proxy — block dangerous operations without touching the server
- **Custom descriptions** — override tool descriptions so AI understands them in context
- **Alias tools** — rename tools per proxy for clarity

### 🏷️ Tool Registry & Discovery
- **Auto-discover** tools from any MCP server (SSE or stdio)
- **Tag, domain, and annotate** tools with business context
- **Glossary terms** — link tools to business concepts for richer descriptions

### 📊 Usage Analytics
- Every tool call is **automatically tracked** with duration, success/failure, and arguments
- **Dashboard** shows top tools, latency trends, and error rates
- Drill into individual call traces with full event timelines

### 🌐 Web Dashboard
Full React SPA for managing everything without touching the CLI:
- Servers, proxies, tools, glossary, analytics
- Edit tool metadata inline
- Real-time stats

---

## Quick Start

### 1. Install

```bash
pip install toolatlas-mcp
```

### 2. Start

```bash
toolatlas start
```

Open **http://localhost:8080** in your browser.

### 3. Add an MCP Server

```bash
# SSH-based MCP server
toolatlas server add my-github \
  --transport stdio \
  --command "npx" \
  --args "-y" "@modelcontextprotocol/server-github"
```

Or add SSE servers via the web UI.

### 4. Create a Proxy

```bash
toolatlas proxy add dev --description "Developer tools"
toolatlas proxy link dev my-github
```

### 5. Connect Your AI Client

Point your MCP client to:

```
http://localhost:8080/proxy/dev/message/{session_id}
```

---

## Architecture

```
┌─────────────────┐     ┌─────────────────────────────────────┐     ┌─────────────────┐
│  MCP Clients    │     │         ToolAtlas                    │     │  MCP Servers     │
│                 │     │                                     │     │                  │
│  Claude         │────▶│  Proxy "dev"    ── governance ──▶ │────▶│  GitHub MCP      │
│  Cursor         │────▶│  Proxy "pm"     ── governance ──▶ │────▶│  Jira MCP        │
│  Custom Agents  │────▶│  Proxy "ops"    ── governance ──▶ │────▶│  Slack MCP       │
│                 │     │                                     │     │  Confluence MCP  │
└─────────────────┘     │  ┌─────────────┐  ┌─────────────┐ │     └─────────────────┘
                        │  │ Registry    │  │ Analytics   │ │
                        │  │ DB + API    │  │ Tracker     │ │
                        │  └─────────────┘  └─────────────┘ │
                        │  ┌──────────────────────────────┐  │
                        │  │  Web Dashboard (React SPA)   │  │
                        │  └──────────────────────────────┘  │
                        └─────────────────────────────────────┘
```

Clients speak MCP to ToolAtlas. ToolAtlas enforces governance, logs everything, and forwards to the real MCP servers.

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `toolatlas start` | Start the ToolAtlas server |
| `toolatlas server add <name>` | Register a new MCP server |
| `toolatlas server list` | List registered servers |
| `toolatlas proxy add <slug>` | Create a new proxy |
| `toolatlas proxy list` | List proxies |
| `toolatlas proxy link <slug> <server>` | Link a server to a proxy |

---

## Configuration

Set via environment variables with `TOOLATLAS_` prefix:

| Variable | Default | Description |
|----------|---------|-------------|
| `TOOLATLAS_HOST` | `127.0.0.1` | Bind address |
| `TOOLATLAS_PORT` | `8080` | HTTP port |
| `TOOLATLAS_DATABASE_URL` | `sqlite+aiosqlite:///toolatlas.db` | Database connection |
| `TOOLATLAS_LOG_LEVEL` | `INFO` | Log level |

---

## Development

```bash
git clone https://github.com/anomalyco/toolatlas-mcp
cd toolatlas-mcp

# Set up Python
pip install -e ".[dev]"

# Set up UI
cd ui && npm install && npm run build && cd ..

# Run tests
pytest

# Start dev server
toolatlas start --reload
# In another terminal: cd ui && npm run dev
```

---

## License

MIT © ToolAtlas contributors
