# Futurmind Expert Digital Twin MCP Server

A Model Context Protocol (MCP) server that provides access to expert digital twins through standardized interface.

## Features

- **Expert Access**: Connect to expert digital twins via API Key
- **Simple Chat**: Single message chat interface
- **Contextual Chat**: Multi-turn conversation with full message history
- **Streaming Support**: Real-time SSE streaming responses
- **Conversation Management**: Track conversations with IDs
- **Header-based Authentication**: Secure API access via X-Api-Key header

## Installation

### Install from PyPI (Recommended)

```bash
pip install futurmind-mcp
```

### Install from Source

```bash
# Clone the repository
git clone <repo-url>
cd futur-mind-mcp

# Install with uv
uv sync

# Or with pip
pip install -e .
```

## Configuration

### Environment Variables

- `FUTURMIND_API_KEY`: Your Futurmind API key (required)
- `FUTURMIND_API_URL`: API base URL (default: https://projectflow-api.futurstaff.com)
- `MCP_TRANSPORT`: Transport type (`stdio` or `http`, default: `stdio`)
- `MCP_PORT`: HTTP port (default: `8000`)
- `MCP_HOST`: HTTP host (default: `localhost`)

## Usage

### Running with stdio transport (for Cursor)

```bash
# Set your API key
export FUTURMIND_API_KEY="your-api-key-here"

# Run the server
python -m futurmind_mcp
```

### Running with HTTP transport

```bash
export FUTURMIND_API_KEY="your-api-key-here"
export MCP_TRANSPORT=http
export MCP_PORT=8000

python -m futurmind_mcp
```

## Docker Deployment (Recommended for Remote Access)

For remote HTTP SSE mode, use Docker:

```bash
# Quick start
./start.sh

# Or manually
cp env.example .env
# Edit .env and set your FUTURMIND_API_KEY
docker-compose up -d
```

See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed Docker deployment guide.

## Cursor Configuration

Add this to your Cursor MCP settings:

### Option 1: stdio transport (recommended for local use)

After installing the package, add this to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "futurmind": {
      "command": "python",
      "args": ["-m", "futurmind_mcp"]
    }
  }
}
```

**Note**: For stdio mode, the API key must be provided via HTTP headers in the client configuration, or you can set `FUTURMIND_API_KEY` environment variable as fallback.

### Option 2: HTTP transport (for remote access)

For HTTP SSE mode, configure the server URL and provide the API key via headers:

```json
{
  "mcpServers": {
    "futurmind": {
      "url": "http://localhost:8000/sse",
      "headers": {
        "X-Api-Key": "your-api-key-here"
      }
    }
  }
}
```

**Note**: The API key is passed via the `X-Api-Key` header for security.

## Available Tools

### 1. chat

Simple single-message chat interface.

**Parameters:**
- `message` (string, required): Your message
- `conversation_id` (string, optional): Conversation UUID for context
- `dify_conversation_id` (string, optional): Dify conversation ID
- `user_id` (string, optional): User ID

**Example:**
chat_with_context(
messages_json='[{"role":"user","content":"Hello"},{"role":"assistant","content":"Hi!"},{"role":"user","content":"How are you?"}]',
conversation_id="uuid-here"
)
## API Reference

The server forwards requests to:
- **Endpoint**: `POST /v1/zhiyin/chat/stream`
- **Headers**: `X-Api-Key: your-api-key`
- **Request Body**: CompletionRequestZhiyin
- **Response**: SSE stream of CompletionEvent

## License

MIT