FastMCP Server

A high-performance personal Model Context Protocol (MCP) server built with the FastMCP Python framework.

Project Structure

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:

source venv/bin/activate
pip install -r requirements.txt

[!TIP] Alternatively, you can install the package in editable mode:

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:

cp fastmcp.json.example fastmcp.json
fastmcp run fastmcp.json

Option B: Standard Python (STDIO Only)

Run the module directly:

python -m mcp_server.server

Option C: Dev Mode (MCP Inspector)

Start the interactive developer interface to inspect tools and resources:

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:

  "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

"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:

"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:

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:

  {
    "mcpServers": {
      "personal-mcp-server": {
        "command": "/absolute/path/to/mcp-server/venv/bin/python",
        "args": ["-m", "mcp_server.server"]
      }
    }
  }
  

• For HTTP Transport:

  {
    "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:

   cp upstream_servers.json.example upstream_servers.json
   

2. Configure your upstream servers under the mcpServers object in upstream_servers.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 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:

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:

docker compose ps
docker compose logs -f

---

CI/CD Pipeline (GitHub Actions)

A GitHub Actions workflow is configured in .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.