# 📚 MCP Server Integration Guide

This guide provides instructions on how to configure your Fullstack Context MCP Server with various AI clients (Claude Desktop, Cursor, VS Code/Cline, Gemini CLI).

## ⚠️ Prerequisites

1.  **Absolute Paths Only:** MCP clients rarely understand relative paths like `.` or `~`. Always use full paths (e.g., `/Users/name/project` or `C:\Users\name\project`).
2.  **Python Environment:** Ensure `mcp` is installed in the python environment you are pointing to.

---

## 🛑 IMPORTANT: Workspace Restrictions (Sandboxing)

**Read this if you use VS Code, Cursor, or Windsurf.**

Even if you configure `PATH_BACKEND` correctly in the JSON settings, the AI Agent (Client) typically operates inside a **Security Sandbox**. It often refuses to execute tools or read files that are **outside** the currently open window/folder to prevent unauthorized access.

**The Fix: Multi-Root Workspace**
To allow the AI to access your external backend folder via MCP, you must explicitly trust it by adding it to your current workspace:

1.  Open your Frontend project in the editor.
2.  Go to **File** > **Add Folder to Workspace...**
3.  Select your Backend folder (e.g., `/path/to/backend-project`).
4.  (Optional) Save this setup: **File** > **Save Workspace As...**

**Result:** Both folders are now "inside" the trusted zone. The MCP server will now work correctly without being blocked by the editor's security layer.

---

## 1. Claude Desktop App (MacOS / Windows)

Claude Desktop is currently the standard implementation for MCP and is less strict about workspace sandboxing than VS Code.

**Configuration File Location:**
*   **MacOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
*   **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

**Setup Steps:**
1.  Open the configuration file in a text editor.
2.  Add your server under `mcpServers`.

```json
{
  "mcpServers": {
    "fullstack-server": {
      "command": "python3",
      "args": [
        "/absolute/path/to/your/repo/server.py"
      ],
      "env": {
        "PATH_FRONTEND": "/absolute/path/to/frontend-project",
        "PATH_BACKEND": "/absolute/path/to/backend-project"
      }
    }
  }
}
```
**Note:** If you use a virtual environment (venv), replace `"python3"` with the path to the python executable inside the venv.

## 2. Cursor (AI Editor)
Cursor creates a bridge to local scripts via its "Features" settings.

**Setup Steps:**
1.  Open Cursor Settings (`Ctrl + ,` or `Cmd + ,`).
2.  Go to `Features` -> `MCP Servers`.
3.  Click "Add New Server".
4.  Fill in the details:
    *   **Name:** `Fullstack Context`
    *   **Type:** `Command (stdio)`
    *   **Command:**
        ```bash
        python3 /absolute/path/to/your/repo/server.py
        ```
    *   **Environment Variables:**
        *   `PATH_FRONTEND`: `/absolute/path/to/frontend-project`
        *   `PATH_BACKEND`: `/absolute/path/to/backend-project`

**Crucial Step:** Ensure you add both Frontend and Backend folders to the workspace (**File** > **Add Folder to Workspace**) so the AI has permission to use the MCP tools on them.

## 3. VS Code (via Cline / Roo Code)
VS Code Native does not support MCP yet. You must use the Cline (formerly Claude Dev) or Roo Code extension.

**Setup Steps:**
1.  Install Cline from VS Code Marketplace.
2.  Open Cline in the sidebar.
3.  Click the MCP Server Icon (Database icon) or Settings.
4.  Select "Edit MCP Settings".
5.  Paste the configuration:

```json
{
  "mcpServers": {
    "fullstack-server": {
      "command": "python",
      "args": ["/absolute/path/to/your/repo/server.py"],
      "env": {
        "PATH_FRONTEND": "/absolute/path/to/frontend-project",
        "PATH_BACKEND": "/absolute/path/to/backend-project",
        "PYTHONUTF8": "1"
      }
    }
  }
}
```
⚠️ **Important:** VS Code is very strict. If `PATH_BACKEND` is outside the current window, you MUST use **File** > **Add Folder to Workspace** to include that folder, otherwise Cline will refuse to run the tool or read files from it.

## 4. Google Gemini CLI (npm)
This section explains how to connect the official npm `gemini-cli` to this MCP server.

**Setup Steps:**
1.  **Install and Authenticate Gemini CLI:**
    ```bash
    npm install -g @google/gemini-cli
    gemini configure
    ```
2.  **Configure Gemini CLI for MCP:**
    Open the Gemini CLI configuration file. Its location varies by OS:
    *   **Linux/macOS:** `~/.config/@google-gemini-cli/config.json`
    *   **Windows:** `%APPDATA%\@google-gemini-cli\config.json`

    Add your server configuration under the `mcpServers` section:

```json
{
  "mcpServers": {
    "fullstack-server": {
      "command": "python3",
      "args": [
        "/absolute/path/to/your/repo/server.py"
      ],
      "env": {
        "PATH_FRONTEND": "/absolute/path/to/frontend-project",
        "PATH_BACKEND": "/absolute/path/to/backend-project"
      }
    }
  }
}
```

**Note:** Ensure that `/absolute/path/to/your/repo/server.py` points to the correct location of your MCP server script. Replace `/absolute/path/to/frontend-project` and `/absolute/path/to/backend-project` with the actual absolute paths to your frontend and backend project directories, respectively.