# FastMCP Server

A high-performance personal Model Context Protocol (MCP) server built with the [FastMCP](https://github.com/prefecthq/fastmcp) Python framework.

## Project Structure

```text
mcp-server/
├── .agents/
│   └── mcp_config.json.example  # IDE/agent configurations template
├── src/
│   └── mcp_server/
│       ├── __init__.py          # Package initialization
│       └── server.py            # Main server logic (tools, resources, prompts)
├── fastmcp.json.example         # FastMCP CLI config template
├── pyproject.toml               # Poetry/Setuptools metadata and dependencies
└── requirements.txt             # Pip installation file
```

---

## Features Scaffolded

*   **Tools** (executable actions):
    *   `add_numbers(a, b)`: Adds two floats together.
    *   `format_message(name, message)`: Returns a formatted greeting.
    *   `save_user_profile(username, profile_content)`: Dynamically saves/updates a user profile in the active database.
    *   `save_wiki_article(topic, markdown_content)`: Dynamically saves/updates markdown wiki pages in the active database.
*   **Resources** (data exposed to LLMs):
    *   `config://system_info`: Static resource returning OS and Python environment details.
    *   `user://{username}`: Dynamic resource returning profile data (queries database, falls back to defaults).
    *   `wiki://{topic}`: Dynamic resource returning markdown wiki articles (queries database, falls back to default bootstrap guides).
*   **Prompts** (instruction templates):
    *   `code_reviewer(code, language)`: Generates structured instructions to review code.

---

## Installation & Setup

### 1. Configure the Virtual Environment
Ensure you are using the local virtual environment:
```bash
source venv/bin/activate
pip install -r requirements.txt
```

> [!TIP]
> Alternatively, you can install the package in editable mode:
> ```bash
> pip install -e .
> ```

### 2. Run the Server
You can run the server in two modes:

#### Option A: CLI Config (Recommended)
Copy the example config and run with the `fastmcp` CLI:
```bash
cp fastmcp.json.example fastmcp.json
fastmcp run fastmcp.json
```

#### Option B: Standard Python (STDIO Only)
Run the module directly:
```bash
python -m mcp_server.server
```

#### Option C: Dev Mode (MCP Inspector)
Start the interactive developer interface to inspect tools and resources:
```bash
fastmcp dev src/mcp_server/server.py
```

---

## Storage & Caching Backend

The server integrates a storage layer that powers user profiles and response caching. It can switch between a local, volatile `memory` store (development) and `redis` (production).

### Configuration Options
Configure the backend inside your `fastmcp.json` file:
```json
  "storage": {
    "backend": "memory",
    "redis": {
      "host": "localhost",
      "port": 6379,
      "db": 0,
      "cache_db": 1
    }
  }
```

Alternatively, settings can be loaded from environment variables (e.g. in your `.env` file):
- `STORAGE_BACKEND`: `memory` or `redis`
- `REDIS_HOST`: Hostname (default: `localhost`)
- `REDIS_PORT`: Port number (default: `6379`)
- `REDIS_DB`: Default database index (default: `0`)
- `REDIS_STORAGE_DB`: Specific storage database index (defaults to `REDIS_DB`)
- `REDIS_CACHE_DB`: Specific cache database index (default: `1`)
- `REDIS_PASSWORD`: Optional authentication password

---


## Integrations

### 1. Claude Desktop
Add this server to your local configuration:
*   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
*   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add one of the following setups under the `mcpServers` object:

#### STDIO Connection
```json
"personal-mcp-server": {
  "command": "/absolute/path/to/mcp-server/venv/bin/python",
  "args": ["-m", "mcp_server.server"]
}
```
*(Make sure to replace `/absolute/path/to/mcp-server` with your actual workspace path).*

#### HTTP SSE Connection
Start the server in HTTP mode first (`fastmcp run fastmcp.json`), then hook it up using `mcp-remote`:
```json
"personal-mcp-server": {
  "command": "npx",
  "args": [
    "mcp-remote@latest",
    "--sse",
    "--allow-http",
    "http://localhost:8000/sse"
  ]
}
```

---

### 2. Antigravity IDE
Configure the server for the workspace agent panel.

#### Step 1: Initialize Workspace Configuration
Copy the configuration template:
```bash
cp .agents/mcp_config.json.example .agents/mcp_config.json
```

#### Step 2: Configure Transport
Open `.agents/mcp_config.json` and configure either `stdio` or `http`:

*   **For STDIO Transport:**
    ```json
    {
      "mcpServers": {
        "personal-mcp-server": {
          "command": "/absolute/path/to/mcp-server/venv/bin/python",
          "args": ["-m", "mcp_server.server"]
        }
      }
    }
    ```
*   **For HTTP Transport:**
    ```json
    {
      "mcpServers": {
        "personal-mcp-server": {
          "serverUrl": "http://localhost:8000/sse"
        }
      }
    }
    ```

> [!NOTE]
> Global configuration can also be set in `~/.gemini/config/mcp_config.json`.

---

## Upstream MCP Server Composition

You can configure this server to connect to, aggregate, and namespace other local or remote MCP servers. This is called **Server Composition**.

When upstream servers are mounted:
- All their tools, resources, and prompts are exposed under their respective `namespace` prefix (e.g., if you mount `git`, its tools will be prefixed like `git_list_commits` to avoid naming collisions).

### Setup Upstream Servers
1. Copy the example configuration template:
   ```bash
   cp upstream_servers.json.example upstream_servers.json
   ```
2. Configure your upstream servers under the `mcpServers` object in `upstream_servers.json`:
   ```json
   {
     "mcpServers": {
       "git": {
         "command": "uvx",
         "args": ["mcp-server-git"]
       },
       "remote-helper": {
         "serverUrl": "http://localhost:8001/sse"
       }
     }
   }
   ```
3. Run or restart the FastMCP server. The configured servers will be dynamically mounted and namespaces on startup.

---

## Container Deployment (Docker & Compose)

A complete, self-contained **[docker-compose.yml](file:///workspaces/mcp-server/docker-compose.yml)** file is provided that launches the entire architecture locally:
- **`traefik`**: Routes incoming HTTP requests from the host (`http://mcp.localhost`) to the server.
- **`redis`**: Standard `redis:8.8-alpine` key-value store database used for user profiles and FastMCP response caching.
- **`mcp-server`**: Pulls and launches the python server from GHCR, connecting to Redis and registering discovery labels for Traefik routing.

### How to Run:
Start all services:
```bash
docker compose up -d
```

This will:
1. Pull the pre-built server image `ghcr.io/jamesbspencer/mcp-server:latest` from GitHub Container Registry.
2. Start the Traefik proxy on port `80` (HTTP) and expose its dashboard interface on `http://localhost:8080`.
3. Start the Redis instance with a persistent named volume `redis-data`.
4. Connect all services on a custom `mcp-network` bridge network.

### Verification & Logs
You can check service status and logs using:
```bash
docker compose ps
docker compose logs -f
```

---

## CI/CD Pipeline (GitHub Actions)

A GitHub Actions workflow is configured in **[.github/workflows/docker-publish.yml](file:///workspaces/mcp-server/.github/workflows/docker-publish.yml)** to automatically build and publish your server image to **GitHub Container Registry (GHCR)**.

### Triggers:
- On push to `main` or `master` branches (builds and pushes tag matching the branch name).
- On push of version tags (e.g., `v1.2.3`).
- Can be manually triggered via `workflow_dispatch`.

The workflow extracts semver metadata and configures build cache (`cache-from: type=gha`) for fast incremental builds.