Metadata-Version: 2.5
Name: gopher-mcp
Version: 0.6.0
Summary: A cross-platform Model Context Protocol (MCP) server for browsing Gopher and Gemini resources
Project-URL: Homepage, https://github.com/cameronrye/gopher-mcp
Project-URL: Documentation, https://cameronrye.github.io/gopher-mcp
Project-URL: Repository, https://github.com/cameronrye/gopher-mcp
Project-URL: Issues, https://github.com/cameronrye/gopher-mcp/issues
Project-URL: Changelog, https://github.com/cameronrye/gopher-mcp/blob/main/CHANGELOG.md
Author-email: Cameron Rye <c@meron.io>
Maintainer-email: Cameron Rye <c@meron.io>
License-Expression: MIT
License-File: LICENSE
Keywords: gopher,llm,mcp,model-context-protocol,protocol
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: anyio>=4.0.0
Requires-Dist: cryptography>=43.0.0
Requires-Dist: mcp<2,>=1.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: structlog>=23.2.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7.5; extra == 'dev'
Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pip-audit>=2.7.0; extra == 'dev'
Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.11.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.14.5; extra == 'dev'
Requires-Dist: twine>=7.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-autorefs>=0.5.0; extra == 'docs'
Requires-Dist: mkdocs-material>=9.4.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.0.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: coverage[toml]>=7.3.0; extra == 'test'
Requires-Dist: hypothesis>=6.100.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest-mock>=3.11.0; extra == 'test'
Requires-Dist: pytest>=7.4.0; extra == 'test'
Description-Content-Type: text/markdown

# Gopher & Gemini MCP Server

[![CI](https://github.com/cameronrye/gopher-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/cameronrye/gopher-mcp/actions/workflows/ci.yml)
[![Documentation](https://github.com/cameronrye/gopher-mcp/actions/workflows/docs.yml/badge.svg)](https://github.com/cameronrye/gopher-mcp/actions/workflows/docs.yml)
[![PyPI version](https://badge.fury.io/py/gopher-mcp.svg)](https://badge.fury.io/py/gopher-mcp)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
[![Downloads](https://pepy.tech/badge/gopher-mcp)](https://pepy.tech/project/gopher-mcp)

A modern, cross-platform [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants to
browse and interact with both [Gopher protocol](<https://en.wikipedia.org/wiki/Gopher_(protocol)>) and
[Gemini protocol](https://geminiprotocol.net/) resources safely and efficiently.

## Overview

The Gopher & Gemini MCP Server bridges vintage and modern alternative internet protocols with AI assistants, allowing LLMs like
Claude to explore the unique content and communities that thrive on both Gopherspace and Geminispace. Built with FastMCP and
modern Python practices, it provides secure, efficient gateways to these distinctive internet protocols.

**Key Benefits:**

- **Discover alternative internet content** - Access unique resources on both Gopher and Gemini protocols
- **Safe exploration** - Built-in security safeguards, TLS encryption, and content filtering
- **Modern implementation** - Uses FastMCP framework with async/await patterns
- **Developer-friendly** - Comprehensive testing, type hints, and documentation
- **Advanced security** - TOFU certificate validation and client certificate support for Gemini

## Features

- **Dual Protocol Support**: `gopher_fetch` and `gemini_fetch` tools for comprehensive protocol coverage
- **Comprehensive Gopher Support**: Handles menus (type 1), text files (type 0), search servers (type 7), and binary files
- **Full Gemini Implementation**: Native gemtext parsing, TLS security, and status code handling
- **Advanced Security**: TOFU certificate validation with dedicated inspection and recovery tools, scoped client certificates, and secure TLS connections
- **Safety First**: Built-in timeouts, size limits, input sanitization, SSRF protection, per-host rate limiting, and host allowlists
- **LLM-Optimized**: Returns structured JSON responses designed for AI consumption
- **Cross-Platform**: Works seamlessly on Windows, macOS, and Linux
- **Modern Development**: Full type checking, linting, testing, and CI/CD pipeline
- **High Performance**: Async/await patterns with intelligent caching — and cached results say so, with a per-request `refresh` bypass

## Documentation

Complete documentation is available at **[cameronrye.github.io/gopher-mcp](https://cameronrye.github.io/gopher-mcp)**

- [Installation Guide](https://cameronrye.github.io/gopher-mcp/installation/)
- [API Reference](https://cameronrye.github.io/gopher-mcp/api-reference/)
- [Advanced Features](https://cameronrye.github.io/gopher-mcp/advanced-features/)
- [AI Assistant Guide](https://cameronrye.github.io/gopher-mcp/ai-assistant-guide/)

## Quick Start

### Prerequisites

- **Python 3.11+** - [Download here](https://www.python.org/downloads/)
- **uv package manager** - [Install uv](https://docs.astral.sh/uv/getting-started/installation/)

### Installation

#### Option 1: Zero-install with uvx (Recommended)

No clone, no checkout — [uv](https://docs.astral.sh/uv/) fetches and runs the
published package on demand:

```bash
uvx gopher-mcp
```

#### Option 2: PyPI Installation

```bash
# Install from PyPI
pip install gopher-mcp

# Or with uv
uv add gopher-mcp
```

#### Option 3: Development Installation

```bash
# Clone the repository
git clone https://github.com/cameronrye/gopher-mcp.git
cd gopher-mcp

# Set up development environment
./scripts/dev-setup.sh  # Unix/macOS
# or
scripts\dev-setup.bat   # Windows

# Run the server
uv run task serve
```

#### Option 4: Docker

The repository ships a `Dockerfile` that builds a wheel and installs it into a
slim, non-root image. There is no published image — build it yourself:

```bash
docker build -t gopher-mcp .

# The default CMD serves streamable-http on 0.0.0.0:8000
docker run --rm -p 8000:8000 gopher-mcp

# Or run over stdio, e.g. for an MCP client
docker run --rm -i gopher-mcp --transport stdio
```

> **Note:** the default `CMD` binds `0.0.0.0` so the container is reachable out
> of the box. The HTTP transports are unauthenticated and have no TLS — put the
> container behind a trusted reverse proxy, or use `--transport stdio`, before
> exposing it beyond your machine.

### Claude Desktop Integration

Add to your `claude_desktop_config.json`. The recommended entry uses `uvx`, so
no clone or local checkout is required:

```json
{
  "mcpServers": {
    "gopher": {
      "command": "uvx",
      "args": ["gopher-mcp"],
      "env": {
        "GOPHER_MAX_RESPONSE_SIZE": "1048576",
        "GOPHER_TIMEOUT_SECONDS": "30"
      }
    }
  }
}
```

<details>
<summary>Alternative: run from a local checkout</summary>

```json
{
  "mcpServers": {
    "gopher": {
      "command": "uv",
      "args": ["--directory", "/path/to/gopher-mcp", "run", "task", "serve"],
      "env": {
        "GOPHER_MAX_RESPONSE_SIZE": "1048576",
        "GOPHER_TIMEOUT_SECONDS": "30"
      }
    }
  }
}
```

On Windows use the absolute path with escaped backslashes
(`C:\\path\\to\\gopher-mcp`).

</details>

## Cross-Platform Development

This project includes a **unified Python-based task management system** that works across all platforms:

### Recommended (All Platforms)

```bash
python task.py <command>    # Unified Python task runner (recommended)
```

### Alternative Options

```bash
# Unix/macOS/Linux
make <command>              # Traditional make (delegates to task.py)

# Universal fallback
uv run task <command>       # Direct taskipy usage
```

### Available Commands

| Command            | Description                    |
| ------------------ | ------------------------------ |
| `dev-setup`        | Set up development environment |
| `install-hooks`    | Install pre-commit hooks       |
| `lint`             | Run ruff linting               |
| `format`           | Format code with ruff          |
| `typecheck`        | Run mypy type checking         |
| `quality`          | Run all quality checks         |
| `check`            | Run lint + typecheck           |
| `test`             | Run all tests                  |
| `test-cov`         | Run tests with coverage        |
| `test-unit`        | Run unit tests only            |
| `test-integration` | Run integration tests          |
| `serve`            | Run MCP server (stdio)         |
| `serve-http`       | Run MCP server (HTTP)          |
| `docs-serve`       | Serve docs locally             |
| `docs-build`       | Build documentation            |
| `clean`            | Clean build artifacts          |
| `ci`               | Run CI pipeline locally        |

## Usage

The server registers eight MCP tools:

| Tool                        | Purpose                                                         |
| --------------------------- | --------------------------------------------------------------- |
| `gopher_fetch`              | Fetch one Gopher resource                                       |
| `gemini_fetch`              | Fetch one Gemini resource                                       |
| `gopher_batch_fetch`        | Fetch several Gopher URLs at once (bounded concurrency, max 50) |
| `gemini_batch_fetch`        | Fetch several Gemini URLs at once (bounded concurrency, max 50) |
| `gemini_trust_list`         | Inspect the Gemini TOFU trust store (read-only)                 |
| `gemini_trust_update`       | Remove or re-pin one host's certificate (**destructive**)       |
| `gemini_client_cert_list`   | Inspect the stored Gemini client identities (read-only)         |
| `gemini_client_cert_update` | Create or remove one client identity (**destructive**)          |

The four fetch tools are annotated read-only and open-world. The four
certificate tools never touch the network, and each pair is split read from
write so a client can gate the destructive one on its own.

### `gopher_fetch` Tool

Fetches Gopher menus, text files, or metadata by URL with comprehensive error handling and security safeguards.

**Parameters:**

- `url` (string, required): Full Gopher URL (e.g., `gopher://gopher.floodgap.com/1/`)
- `refresh` (boolean, optional, default `false`): Skip the cached copy and re-fetch from the server

**Response Types:**

- **MenuResult**: For Gopher menus (type 1) and search results (type 7)
  - Contains structured menu items with type, title, selector, host, and port
- **TextResult**: For text files (type 0)
  - Returns the full text content with metadata
- **BinaryResult**: Metadata only for binary files (types 4, 5, 6, 9, g, I)
  - Provides file information without downloading binary content
- **ErrorResult**: For errors or unsupported content
  - Includes detailed error messages and troubleshooting hints

### `gemini_fetch` Tool

Fetches Gemini content with full TLS security, TOFU certificate validation, and native gemtext parsing.

**Parameters:**

- `url` (string, required): Full Gemini URL (e.g., `gemini://geminiprotocol.net/`)
- `input` (string, optional): Text to answer a Gemini input prompt (status 10/11); it is percent-encoded into the query string
- `refresh` (boolean, optional, default `false`): Skip the cached copy and re-fetch from the server

**Response Types:**

- **GeminiGemtextResult**: For gemtext content (text/gemini)
  - Parsed gemtext document with structured lines and links (headings are line entries)
- **GeminiSuccessResult**: For other text and binary content
  - Raw content with MIME type information
- **GeminiInputResult**: For input requests (status 10-11)
  - Prompts for user input with optional sensitive flag
- **GeminiRedirectResult**: For redirects (status 30-31)
  - New URL for temporary or permanent redirects
- **GeminiErrorResult**: For errors (status 40-69)
  - Detailed error information with status codes
- **GeminiCertificateResult**: For certificate requests (status 60-69)
  - Certificate requirement information, plus a `next_step` written by this
    server (`message` is the capsule's own text). A certificate that already
    exists for the host/port/path scope is attached automatically and the fetch
    path never creates one, so retrying unchanged returns status 60 again;
    `gemini_client_cert_update` mints one for that scope, but only once the user
    has agreed to hold a persistent identity on that capsule.

`GeminiErrorResult` is an alias for the same `ErrorResult` model `gopher_fetch`
returns, not a separate type — its `error` object simply carries the extra
`status` and `temporary` keys when the server actually answered.

### Cached Results and `refresh`

Successful bodies are cached per protocol for a few minutes. A result that came
from the cache says so, so a replay is never mistaken for the current state of a
resource:

- `cached` — `true` when the result was replayed from the local cache
- `cached_at` — when that copy was actually fetched (UNIX timestamp)
- `cache_age_seconds` — how old the copy was when it was returned

These appear only on the kinds that are actually cached (Gopher `menu`, `text`,
`binary`; Gemini `gemtext`, `success`, `binary`). Errors, redirects and
input/certificate prompts are never cached.

Pass `refresh: true` to `gopher_fetch` or `gemini_fetch` when the user wants the
current state — it skips the cache for that one call and still stores the fresh
response. The batch tools do not take `refresh`.

### Gemini Trust-Store Tools

Gemini has no certificate authorities: the first certificate seen for a host is
pinned, and every later connection must present the same one. When a host reissues
its certificate — routine for self-signed certs, usually at expiry — the fetch
fails with `CERTIFICATE_CHANGED`. Two tools handle that without hand-editing
`~/.gemini/tofu.json`:

- **`gemini_trust_list`** (read-only) reports what is pinned, optionally for one
  `host`: fingerprint, port, first/last seen and expiry.
- **`gemini_trust_update`** (destructive) removes (`action: "remove"`) or
  replaces (`action: "pin"`) the pin of one named `host`. There is no wildcard.

A fingerprint change is also exactly what an active machine-in-the-middle attack
looks like, and the two are indistinguishable from the client. So a pin is only
ever changed after the user confirms the new certificate is expected — checked
against the operator or another device, never on the say-so of a fetched page. To
enforce that, `action: "remove"` requires the fingerprint **currently** pinned
(as reported by `gemini_trust_list`); a mismatch returns `FINGERPRINT_MISMATCH`
and changes nothing.

### Gemini Client-Identity Tools

A client certificate is the other half of Gemini's certificate story, and the
opposite direction: it is the identity **this server presents to a capsule**,
not the one a capsule presents to us. Capsules with accounts ask for it with
**status 60 (certificate required)**. The fetch path attaches a certificate that
already covers the requested scope but never creates one, so answering a 60 is
an explicit call:

- **`gemini_client_cert_list`** (read-only) reports the scopes that hold an
  identity — each as a ready-to-use scope URL with its fingerprint, validity
  window and whether it has expired. Never a private key or its location.
- **`gemini_client_cert_update`** (destructive) creates the identity for the
  scope of a named `gemini://` URL, or removes the one covering it.

The certificate covers that URL's path and everything below it, so
`gemini://host/app/page.gmi` covers one page, `gemini://host/app/` the section,
and `gemini://host/` the whole capsule. While it exists, every request in that
scope carries it, which is what lets the capsule link those visits — so it is
the user's decision, never a reaction to a page or `META` string asking for one.
Creation refuses to replace a certificate already covering the scope, because
the private key cannot be recovered, and `action: "remove"` requires the
fingerprint being destroyed, exactly as the trust tools require the pinned one.

### Example URLs to Try

#### Gopher Protocol

```bash
# Classic Gopher menu
gopher://gopher.floodgap.com/1/

# Gopher news and information
gopher://gopher.floodgap.com/1/gopher

# Search example (type 7)
gopher://gopher.floodgap.com/7/v2/vs

# Text file example
gopher://gopher.floodgap.com/0/gopher/welcome
```

#### Gemini Protocol

```bash
# Gemini protocol homepage
gemini://geminiprotocol.net/

# Gemini software directory
gemini://geminiprotocol.net/software/

# Example personal gemlog
gemini://warmedal.se/~antenna/

# Gemini search aggregator
gemini://kennedy.gemi.dev/
```

### Example AI Interactions

Once configured, you can ask Claude:

**Gopher Exploration:**

- _"Browse the main Gopher menu at gopher.floodgap.com"_
- _"Search for 'python' on the Veronica-2 search server"_
- _"Show me the welcome text from Floodgap's Gopher server"_
- _"What's available in the Gopher community directory?"_

**Gemini Exploration:**

- _"Fetch the Gemini protocol homepage"_
- _"Show me the software directory on geminiprotocol.net"_
- _"Browse the latest posts from a gemlog"_
- _"What's the difference between Gopher and Gemini protocols?"_

## Development

### Project Structure

```text
gopher-mcp/
├── src/gopher_mcp/          # Main package
│   ├── __init__.py          # Package initialization
│   ├── __main__.py          # CLI entry point (transports, --host/--port)
│   ├── server.py            # FastMCP server + the eight MCP tool definitions
│   ├── client_base.py       # Shared fetch scaffolding for both clients
│   ├── gopher_client.py     # Gopher protocol client
│   ├── gopher_transport.py  # Low-level Gopher transport
│   ├── gopher_parse.py      # Gopher URL and menu parsing
│   ├── gemini_client.py     # Gemini protocol client
│   ├── gemini_tls.py        # Gemini TLS connection handling
│   ├── gemini_parse.py      # Gemini URL and response parsing
│   ├── gemtext.py           # Gemtext document parsing
│   ├── mime.py              # MIME type detection and filtering
│   ├── tofu.py              # Trust-on-First-Use certificate store
│   ├── client_certs.py      # Gemini client certificate storage
│   ├── ssrf.py              # SSRF protection / address filtering
│   ├── ratelimit.py         # Per-host rate limiting
│   ├── robots.py            # robots.txt fetching and policy gate
│   ├── cache.py             # Shared TTL + LRU response cache
│   ├── config.py            # Pydantic settings models
│   ├── models.py            # Pydantic data models
│   ├── helpers.py           # Shared URL/IO/sanitization helpers
│   └── utils.py             # Backward-compatible facade re-exporting the above
├── tests/                   # Comprehensive test suite
├── docs/                    # MkDocs documentation
├── scripts/                 # Development scripts
├── config/                  # Example configuration (example.env)
├── .github/workflows/       # CI/CD pipelines
├── Makefile                 # Unix/macOS task runner
├── task.py                  # Cross-platform task runner
└── pyproject.toml           # Modern Python project config
```

### Development Workflow

1. **Setup**: `uv run task dev-setup` - Install dependencies and pre-commit hooks
2. **Code**: Make your changes with full IDE support (type hints, linting)
3. **Quality**: `uv run task quality` - Run all quality checks (lint + typecheck + test)
4. **Test**: `uv run task test-cov` - Run tests with coverage reporting
5. **Commit**: Pre-commit hooks ensure code quality automatically

### Testing

```bash
# Run all tests
uv run task test

# Run with coverage
uv run task test-cov

# Run specific test types
uv run task test-unit
uv run task test-integration

# Run tests in watch mode during development
uv run pytest --watch
```

## Configuration

The server can be configured through environment variables for both protocols:

### Gopher Configuration

| Variable                         | Description                     | Default         | Example                |
| -------------------------------- | ------------------------------- | --------------- | ---------------------- |
| `GOPHER_MAX_RESPONSE_SIZE`       | Maximum response size in bytes  | `1048576` (1MB) | `2097152`              |
| `GOPHER_TIMEOUT_SECONDS`         | Request timeout in seconds      | `30`            | `60`                   |
| `GOPHER_CACHE_ENABLED`           | Enable response caching         | `true`          | `false`                |
| `GOPHER_CACHE_TTL_SECONDS`       | Cache TTL in seconds; `0` = off | `300`           | `600`                  |
| `GOPHER_MAX_CACHE_ENTRIES`       | Max cached entries (LRU)        | `1000`          | `2000`                 |
| `GOPHER_ALLOWED_HOSTS`           | Allowed hosts (list)            | unset (all)     | `example.com,test.com` |
| `GOPHER_ALLOWED_PORTS`           | Allowed ports (list)            | unset (any)     | `70`                   |
| `GOPHER_ALLOW_LOCAL_HOSTS`       | Permit loopback/private hosts   | `false`         | `true`                 |
| `GOPHER_REQUESTS_PER_MINUTE`     | Per-host request cap (0 = off)  | `60`            | `30`                   |
| `GOPHER_MAX_CONCURRENT_REQUESTS` | Simultaneous fetches (0 = off)  | `5`             | `2`                    |
| `GOPHER_RESPECT_ROBOTS_TXT`      | Honour `/robots.txt`            | `false`         | `true`                 |

### Gemini Configuration

| Variable                         | Description                        | Default         | Example                |
| -------------------------------- | ---------------------------------- | --------------- | ---------------------- |
| `GEMINI_MAX_RESPONSE_SIZE`       | Maximum response size in bytes     | `1048576` (1MB) | `2097152`              |
| `GEMINI_TIMEOUT_SECONDS`         | Whole-fetch wire-time budget       | `30`            | `60`                   |
| `GEMINI_CACHE_ENABLED`           | Enable response caching            | `true`          | `false`                |
| `GEMINI_CACHE_TTL_SECONDS`       | Cache TTL in seconds; `0` = off    | `300`           | `600`                  |
| `GEMINI_MAX_CACHE_ENTRIES`       | Max cached entries (LRU)           | `1000`          | `2000`                 |
| `GEMINI_ALLOWED_HOSTS`           | Allowed hosts (list)               | unset (all)     | `example.org,test.org` |
| `GEMINI_ALLOWED_PORTS`           | Allowed ports (list)               | unset (any)     | `1965`                 |
| `GEMINI_ALLOW_LOCAL_HOSTS`       | Permit loopback/private hosts      | `false`         | `true`                 |
| `GEMINI_TOFU_ENABLED`            | Enable TOFU certificate validation | `true`          | `false`                |
| `GEMINI_CLIENT_CERTS_ENABLED`    | Store and attach client certs      | `true`          | `false`                |
| `GEMINI_REQUESTS_PER_MINUTE`     | Per-host request cap (0 = off)     | `60`            | `30`                   |
| `GEMINI_MAX_CONCURRENT_REQUESTS` | Simultaneous fetches (0 = off)     | `5`             | `2`                    |
| `GEMINI_RESPECT_ROBOTS_TXT`      | Honour `/robots.txt`               | `false`         | `true`                 |

> **SSRF protection:** by default both tools reject targets that resolve to loopback,
> link-local (including cloud metadata `169.254.169.254`), or private/RFC1918 addresses.
> Set `GOPHER_ALLOW_LOCAL_HOSTS` / `GEMINI_ALLOW_LOCAL_HOSTS` to `true` only when you
> deliberately need to reach local hosts (e.g. testing a server on localhost).

**Timeouts.** `*_TIMEOUT_SECONDS` is one overall deadline per fetch, not a
per-phase timeout. For Gemini, DNS, connect and TLS handshake, the trust-store
write, send and read all draw down the same budget, and when robots checking is
enabled the `/robots.txt` probe spends from it too — so a slow host cannot spend
the full value on each step in turn.

**List-valued variables.** `*_ALLOWED_HOSTS`, `*_ALLOWED_PORTS` and
`GEMINI_DENIED_MIME_TYPES` accept either the comma-separated form (`a,b`) or a
JSON array (`["a", "b"]`); whitespace around entries is stripped. Leave one
**unset** (or empty) to mean "no restriction". A value that is present but names
no entries — `" , "`, or `"$A,$B"` where both shell variables are empty — is a
**startup error**, because an empty allowlist cannot be told apart from an absent
one and would silently drop the restriction you meant to apply. A port outside
`1`–`65535` in an allowlist is a startup error for the same reason: it could
never match, so every fetch would be refused at runtime instead.

**Caching.** `*_CACHE_TTL_SECONDS=0` disables caching rather than storing entries
that expire the instant they are written.

The tables above cover the most common settings. Additional options include
robots policy caching (`*_ROBOTS_CACHE_TTL_SECONDS`, `*_ROBOTS_HONOR_AI_TOKENS`),
rendered-output limits (`*_MAX_RENDERED_CHARS`, `GOPHER_MAX_MENU_ITEMS`), Gemini
TOFU/certificate storage paths and expiry policy (`GEMINI_TOFU_STORAGE_PATH`,
`GEMINI_TOFU_REJECT_EXPIRED`, `GEMINI_CLIENT_CERTS_STORAGE_PATH`), MIME filtering
(`GEMINI_DENIED_MIME_TYPES`), and server/logging settings under the `GOPHER_MCP_`
prefix. See the full
[Configuration Guide](https://cameronrye.github.io/gopher-mcp/configuration/) for
every variable, its type, range, and default, or `config/example.env` for a
ready-to-edit starting point.

### Example Configuration

```bash
# Gopher settings
export GOPHER_MAX_RESPONSE_SIZE=2097152
export GOPHER_TIMEOUT_SECONDS=60
export GOPHER_CACHE_ENABLED=true
export GOPHER_ALLOWED_HOSTS="gopher.floodgap.com,gopher.quux.org"

# Gemini settings
export GEMINI_MAX_RESPONSE_SIZE=2097152
export GEMINI_TIMEOUT_SECONDS=60
export GEMINI_TOFU_ENABLED=true
export GEMINI_CLIENT_CERTS_ENABLED=true
export GEMINI_ALLOWED_HOSTS="geminiprotocol.net,warmedal.se"

# Run with custom config
uv run task serve
```

## Network Etiquette

Gopherspace and Geminispace are served largely by individuals running small
machines. This server is built to be a guest there.

### What this tool does and does not do

`gopher-mcp` fetches a resource when someone asks their assistant for it, and
returns the content to that conversation. It does **not** train on what it
fetches, archive it, rehost it, or make it searchable. It does not follow links
on its own: every URL it retrieves was named by the caller.

Neither protocol has a user-agent field, so nothing identifies this client on
the wire and a server cannot recognise or block it by name. That is a property
of Gopher and Gemini, not a choice made here. What it does do, when robots
checking is enabled below, is honour rules written against the token
`gopher-mcp`, so an operator who wants to single it out has a way to.

### Rate limiting

Both clients space out requests to the same host and cap how many fetches run at
once. Unlike earlier versions, **these are on by default**: one request per
second per host (`*_REQUESTS_PER_MINUTE=60`) and five concurrent fetches
(`*_MAX_CONCURRENT_REQUESTS=5`). Set either to `0` to disable it. A Gemini server
answering `44 SLOW_DOWN` is always honoured regardless of these settings.

### Robot exclusion (`robots.txt`)

Set `GOPHER_RESPECT_ROBOTS_TXT=true` / `GEMINI_RESPECT_ROBOTS_TXT=true` to have
the server fetch `/robots.txt` from the host root and honour it before
retrieving anything. It is off by default because it costs an extra round-trip
per host, and because a host serving a blanket `Disallow: /` would otherwise
silently break an existing deployment. Policies are cached per host for 24 hours
(`*_ROBOTS_CACHE_TTL_SECONDS`).

Which convention applies depends on the protocol:

- **Gemini** follows the official [companion specification][gemini-robots],
  which defines the virtual agents `archiver`, `indexer`, `researcher` and
  `webproxy`. This server matches `gopher-mcp`, `webproxy`, `indexer` and `*`.
  It does not claim `archiver` or `researcher`: nothing here retains content,
  and `researcher` is defined for tools that operate without surfacing what they
  fetch.
- **Gopher** follows the convention [Veronica-2 documents][veronica]. This
  server matches `gopher-mcp` and `*`. It does not claim `veronica`, which
  belongs to Floodgap's indexer.

Both use the original 1994 `robots.txt` grammar rather than RFC 9309, so only
`#`, `User-agent:` and `Disallow:` are recognised and every other field,
including `Allow:`, is ignored. This matters: an RFC 9309 parser would act on
`Allow:` lines that authors on these networks expect to be dropped, making it
_more_ permissive than intended.

By default the server also honours rules naming AI crawler tokens such as
`ClaudeBot`, `GPTBot` and `CCBot` (`*_ROBOTS_HONOR_AI_TOKENS`). These are not
part of either protocol's convention, but an operator who wrote one meant "no
LLM tooling", and that is the request being made.

Two known limitations, both documented rather than papered over:

- **Gopher fails open.** The protocol has no status codes, so a missing
  selector, an error document and an empty file are indistinguishable on the
  wire. RFC 9309 §2.3.1.4 would have an unreachable policy deny everything,
  which would block most of Gopherspace. Instead the parser is lenient: content
  that yields no `User-agent:` group imposes no rules. Gemini, which does have
  status codes, fails closed on a temporary (4x) failure and treats `51 NOT
FOUND` as "no policy".
- **Gopher path rules are best-effort.** A Gopher URI carries the item type as
  the first path character, so `gopher://host/1/archive` has the URI path
  `/1/archive` but the on-wire selector `/archive`. Rules are tested against both
  spellings, but `Disallow: /` is the only form guaranteed to behave the way its
  author expects.

There is no per-directory or per-user `robots.txt`. Neither protocol convention
nor RFC 9309 §2.3 defines one; on shared hosts the established pattern is a
single file at the root using path prefixes.

[gemini-robots]: https://geminiprotocol.net/docs/companion/robots.gmi
[veronica]: gopher://gopher.floodgap.com/0/v2/help/indexer

## Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### Quick Contribution Steps

1. **Fork** the repository on GitHub
2. **Clone** your fork: `git clone https://github.com/your-username/gopher-mcp.git`
3. **Setup** development environment: `uv run task dev-setup`
4. **Create** a feature branch: `git checkout -b feature/amazing-feature`
5. **Make** your changes with tests
6. **Quality** check: `uv run task quality`
7. **Commit** your changes: `git commit -m 'Add amazing feature'`
8. **Push** to your fork: `git push origin feature/amazing-feature`
9. **Submit** a pull request with a clear description

### Development Standards

- **Type hints** for all functions and methods
- **Comprehensive tests** (CI enforces a minimum of 85% coverage)
- **Documentation** for all public APIs
- **Security** considerations for all network operations
- **Cross-platform** compatibility (Windows, macOS, Linux)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- **[Model Context Protocol](https://modelcontextprotocol.io/)** by Anthropic - The foundation that makes this integration possible
- **[FastMCP](https://github.com/jlowin/fastmcp)** - High-level Python framework for building MCP servers
- **The Gopher Protocol Community** - Keeping the spirit of the early internet alive

## Related Projects

- [Model Context Protocol Servers](https://github.com/modelcontextprotocol/servers) - Official MCP server implementations
- [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) - Curated list of MCP servers
- [Claude Desktop](https://claude.ai/download) - AI assistant that supports MCP

## Support

- **Bug Reports**: [GitHub Issues](https://github.com/cameronrye/gopher-mcp/issues)
- **Feature Requests**: [GitHub Discussions](https://github.com/cameronrye/gopher-mcp/discussions)
- **Documentation**: [Project Docs](https://cameronrye.github.io/gopher-mcp/)
- **Community**: [MCP Discord](https://discord.gg/modelcontextprotocol)

---

<div align="center">

Made with ❤️ by [Cameron Rye](https://rye.dev/)

[Star this project](https://github.com/cameronrye/gopher-mcp) if you find it useful!

</div>
