# 🚀 FastAPI AI-Augmented Architecture Boilerplate

A production-ready, out-of-the-box template for building asynchronous AI microservices using Python 3.12, FastAPI, and the Model Context Protocol (MCP).

## ⚡ Core Features
* **Asynchronous API:** Built on FastAPI and Uvicorn for maximum throughput.
* **Conversational AI Agent:** Pre-configured with OpenAI and SQLite for built-in memory and context persistence.
* **Model Context Protocol (MCP):** Exposes a native SSE server for external AI clients (Cursor, Claude Desktop) to autonomously execute backend tools.
* **Containerized Infrastructure:** Fully Dockerized for zero-friction local development and deployment.

## 🚀 Quick Start

**1. Configure the Environment**
Create a `.env` file in the root directory and add your AI provider API key:
```bash
echo "OPENAI_API_KEY=sk-your-key-here" > .env

```

**2. Spin up the Infrastructure**

```bash
docker-compose up -d --build

```

*The FastAPI server will be available at `http://localhost:8000`.*

## 🧪 Testing the Architecture

Once your Docker containers are running, you can immediately verify both the AI memory persistence and the MCP tool execution.

### 1. Testing the Conversational API

We will test if the AI can remember context using the SQLite database.

**Step A: Initiate the Conversation**

```bash
curl -X POST http://localhost:8000/api/chat \
     -H "Content-Type: application/json" \
     -d '{"message": "My favorite framework is FastAPI."}'

```

*Note the `conversation_id` returned in the JSON response.*

**Step B: Test Context Memory**
Pass the ID back to the server to verify database persistence:

```bash
curl -X POST http://localhost:8000/api/chat \
     -H "Content-Type: application/json" \
     -d '{
           "message": "What did I say my favorite framework was?",
           "conversation_id": "PASTE_YOUR_ID_HERE"
         }'

```

### 2. Testing the MCP Server (System Health Tool)

The most professional way to test an MCP Context Provider without an IDE is using the official open-source MCP Inspector.

**Step A: Run the Inspector**
Run this command in your local terminal (requires Node.js):

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

```

**Step B: Execute the Tool**

1. The inspector will open a debugging dashboard in your browser.
2. Navigate to the **Tools** tab.
3. You will see the `system_health` tool automatically listed via the server's handshake.
4. Click **Execute** to watch the MCP server query the Docker environment and return the Python version and SQLite health status in real-time.

## 🔌 Connecting to Cursor / Claude Desktop

To utilize this backend as a context provider in your daily development:

1. Open your AI client's MCP configuration settings.
2. Add a new MCP server connection.
3. Select the **SSE (Server-Sent Events)** transport method.
4. Set the URL to: `http://localhost:8000/mcp/sse`


```