# MCP Server - Knowledge Base Tools

MCP (Model Context Protocol) server exposing knowledge base operations as tools for AI agents.

## Overview

This MCP server provides tools for interacting with the Django backend API to manage and query the knowledge base. All tools require JWT authentication and automatically handle tenant-aware routing.

## Features

- **JWT Authentication**: Token verification using shared secret with Django backend
- **Tenant-aware**: Automatically extracts tenant from JWT and routes to correct backend instance
- **8 Knowledge Base Tools**: Complete set of operations for navigating and managing the knowledge graph

## Installation

1. **Create and activate virtual environment** (recommended):
   ```bash
   python3 -m venv venv
   
   # On macOS/Linux:
   source venv/bin/activate
   
   # On Windows:
   # venv\Scripts\activate
   ```

2. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

3. **Configure environment variables**:
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

## Configuration

### Environment Variables

- `MCP_JWT_SECRET_KEY`: Secret key for JWT token verification (can use `CHAINLIT_JWT_SECRET_KEY` as fallback)
- `MCP_BACKEND_URL`: Backend URL with tenant placeholder, e.g., `http://tenant.localhost:8000` (can use `BACKEND_URL` as fallback)

### Example `.env` file:

```env
MCP_JWT_SECRET_KEY=your-secret-key-here
MCP_BACKEND_URL=http://tenant.localhost:8000
```

## Available Tools

### 1. `get_root_themes_tool`
Get all root theme nodes (top-level folders without parents). Entry point for navigating the knowledge base.

### 2. `get_folder_tree_tool`
Get complete folder tree under a theme node. Returns only themes recursively, excluding skills and knowledge nodes.

### 3. `semantic_search_tool`
Perform semantic search across themes, skills, and knowledge nodes using vector similarity.

### 4. `get_node_children_tool`
Get direct children of a node for downward navigation in the hierarchy.

### 5. `get_node_parents_tool`
Get direct parent nodes for upward navigation in the hierarchy.

### 6. `create_folder_tool`
Create a new theme (folder) node at root or under a parent theme.

### 7. `create_skill_tool`
Create a new skill node under a parent theme.

### 8. `generate_learning_tools_tool`
Generate learning tools (knowledge nodes with questions) for a skill using AI.

## Running the Server

**Make sure your virtual environment is activated** before running the server.

### Start the HTTP/SSE server:

```bash
# Activate venv first
source venv/bin/activate  # On macOS/Linux
# venv\Scripts\activate   # On Windows

python server.py
```

The server will start on `http://0.0.0.0:8100` by default (configurable via environment variables).

### Configuration options:

- `MCP_HOST`: Host to bind (default: `0.0.0.0`)
- `MCP_PORT`: Port number (default: `8100` - port 8000 is used by the Django backend)
- `MCP_TRANSPORT`: Transport type - `sse` (Server-Sent Events) or `streamable-http` (default: `sse`)

### With MCP Inspector (for testing):

1. Start the server:
   ```bash
   python server.py
   ```

2. In MCP Inspector, configure the connection:
   - **Type**: `sse`
   - **URL**: `http://localhost:8100/sse` (use `localhost` not `0.0.0.0` in browser)
   
   Example configuration:
   ```json
   {
     "mcpServers": {
       "knowledge-base": {
         "type": "sse",
         "url": "http://localhost:8100/sse"
       }
     }
   }
   ```

   **Note**: The server binds to `0.0.0.0` but you must use `localhost` or `127.0.0.1` in browser-based clients.

## Usage

All tools require a `jwt_token` parameter containing the user's JWT authentication token. The token should:
- Be a valid JWT signed with the same secret as configured in `MCP_JWT_SECRET_KEY`
- Contain a `tenant` claim for tenant-aware routing
- Be passed as a Bearer token or raw token string

### Example tool call:

```python
result = get_root_themes_tool(
    jwt_token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
)
```

## Architecture

- **`auth.py`**: JWT token verification and tenant extraction
- **`tools.py`**: Core tool functions that interact with Django backend
- **`server.py`**: FastMCP server setup and tool registration

## Security

- All tools verify JWT tokens before processing requests
- Tenant is extracted from token payload (never from user input)
- Backend URL is constructed from token, ensuring tenant isolation
- Invalid or expired tokens return error responses

## Error Handling

All tools return a dictionary with:
- `success: true` and data on success
- `success: false` and `error: "message"` on failure

## Development

The server uses FastMCP, which automatically handles:
- Tool registration
- Request/response serialization
- Error handling
- Logging

## Related Files

- `shad/agents/tools.py`: Original LangChain tools (reference implementation)
- `backend/learn/`: Django backend API endpoints