Metadata-Version: 2.4
Name: unified-nexus
Version: 0.1.0
Summary: One decorator. Two interfaces. Build FastAPI + MCP backends with a single source of truth.
Project-URL: Homepage, https://rajboopathiking.github.io/UnifiedNexus
Project-URL: Repository, https://github.com/rajboopathiking/UnifiedNexus
Project-URL: Documentation, https://rajboopathiking.github.io/UnifiedNexus
Project-URL: Bug Tracker, https://github.com/rajboopathiking/UnifiedNexus/issues
Project-URL: Changelog, https://github.com/rajboopathiking/UnifiedNexus/blob/main/CHANGELOG.md
Author-email: boopathiraj <boopathiraj.aideveloper@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,api,backend,fastapi,fastmcp,llm,mcp,model-context-protocol,rest,unified
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# Unified Nexus

**Unified Nexus** is a high-performance Python framework that bridges the gap between traditional REST APIs and the new world of LLM-native tools (MCP). Build product-grade backends where your web frontend and AI agents share the exact same logic, schemas, and execution paths — defined once.

---

## The Problem

In a traditional stack, you define a FastAPI route, then **manually re-wrap it** as an MCP tool. Over time, these two definitions drift apart — different validation, different schemas, different behavior. This is **Code Drift**, and it silently breaks your AI integrations.

```
❌ Traditional Stack
├── routes/user.py       ← HTTP logic
├── mcp_tools/user.py    ← Copy-pasted MCP logic (already out of sync)
└── models/user.py       ← Shared? Maybe. Hopefully.
```

```
✅ Unified Nexus
└── main.py              ← One function. One decorator. Both interfaces. Always in sync.
```

---

## Installation

```bash
pip install unified-nexus
```

---

## Quick Start

```python
from unified_nexus import UnifiedNexus
from pydantic import BaseModel, Field

nexus = UnifiedNexus("MyNexusAPI")

class UserRequest(BaseModel):
    user_id: int = Field(..., description="The unique ID of the user")

@nexus.universal_tool(path="/user-info")
def get_user(req: UserRequest):
    """
    Fetches user status and clearance level.
    This docstring is used by both Swagger UI and AI Agents automatically.
    """
    return {"id": req.user_id, "status": "Active", "tier": "Gold"}

app = nexus.finalize()

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

Run it:

```bash
python main.py
```

| Interface | URL |
|-----------|-----|
| REST API Docs (Swagger) | http://localhost:8000/docs |
| MCP SSE Endpoint | http://localhost:8000/mcp |
| MCP Inspector | `npx -y @modelcontextprotocol/inspector http://localhost:8000/mcp` |

---

## Core Features

### Single Source of Truth
Define your function once. Unified Nexus simultaneously registers it as a FastAPI route and an MCP tool. Validation, schemas, and business logic are identical for HTTP clients and AI agents — no drift, no duplication.

### Auto-Method Detection
Unified Nexus intelligently selects `GET` or `POST` based on your function signature. Functions with a Pydantic model input default to `POST`; pure query-based functions use `GET`. No configuration needed.

### AI-Native Tool Descriptions
Your Python docstrings become rich, structured tool descriptions for MCP hosts like Claude, Cursor, and Copilot. Descriptive `Field(description=...)` annotations on your Pydantic models are passed directly to the LLM — helping it understand *how* to call your tools correctly.

### Shared Middleware
Apply authentication, rate limiting, or logging once at the `UnifiedNexus` level. The same middleware protects both your HTTP API and your MCP interface — no configuration duplication.

### LLM-Optimized Errors
When your tool raises a Python exception, Unified Nexus converts it into a structured natural-language hint that helps LLMs self-correct their tool calls — rather than returning a raw stack trace the model cannot act on.

### Lifespan-Safe MCP Integration
The `finalize()` method correctly composes FastAPI and FastMCP lifespans, ensuring the MCP `StreamableHTTPSessionManager` task group is always initialized before requests arrive. No runtime errors, no manual wiring.

---

## Architecture

```
Your Code (@universal_tool)
        │
        ▼
  UnifiedNexus.finalize()
     ┌──────┴──────┐
     │             │
  FastAPI        FastMCP
  /docs           /mcp
  REST           SSE/MCP
     │             │
     └──────┬──────┘
            │
      Single ASGI App
      (Uvicorn / any ASGI server)
```

---

## Advanced Usage

### Custom Path and Methods

```python
@nexus.universal_tool(path="/search", methods=["GET"])
def search_items(query: str, limit: int = 10):
    """Search the item catalog. Returns a ranked list of results."""
    return {"results": [...], "total": 42}
```

### Shared Auth Middleware

```python
from unified_nexus.middleware import BearerAuthMiddleware

nexus = UnifiedNexus("SecureAPI")
nexus.add_middleware(BearerAuthMiddleware, token="your-secret-token")
```

### Async Support

```python
@nexus.universal_tool(path="/fetch-data")
async def fetch_external(resource_id: str):
    """Fetches data from an external source asynchronously."""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.example.com/{resource_id}")
    return response.json()
```

---

## Connecting AI Agents

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "my-nexus-api": {
      "url": "http://localhost:8000/mcp",
      "transport": "streamable-http"
    }
  }
}
```

### Cursor / VS Code

Add `http://localhost:8000/mcp` as an MCP server in your editor's AI settings.

### Verify with MCP Inspector

```bash
npx -y @modelcontextprotocol/inspector http://localhost:8000/mcp
```

---

## Requirements

- Python 3.11+
- FastAPI
- FastMCP
- Uvicorn
- Pydantic v2

---

## Contributing

Contributions are welcome! Please open an issue to discuss proposed changes before submitting a PR.
