{"id":31531308,"url":"https://github.com/cameronrye/gopher-mcp","last_synced_at":"2025-12-30T03:24:02.513Z","repository":{"id":315460856,"uuid":"1058184194","full_name":"cameronrye/gopher-mcp","owner":"cameronrye","description":"A modern, cross-platform Model Context Protocol (MCP) server that enables AI assistants to browse and interact with both Gopher protocol and Gemini protocol resources safely and efficiently.","archived":false,"fork":false,"pushed_at":"2025-09-22T10:11:37.000Z","size":456,"stargazers_count":1,"open_issues_count":7,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-30T09:36:48.855Z","etag":null,"topics":["gemini","gemini-protocol","gopher","gopher-protocol","mcp","mcp-server"],"latest_commit_sha":null,"homepage":"https://cameronrye.github.io/gopher-mcp/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cameronrye.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-16T18:29:42.000Z","updated_at":"2025-09-19T02:54:19.000Z","dependencies_parsed_at":"2025-09-18T20:01:59.587Z","dependency_job_id":"7a55c6ba-e3ae-42ec-9359-9109427467eb","html_url":"https://github.com/cameronrye/gopher-mcp","commit_stats":null,"previous_names":["cameronrye/gopher-mcp"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/cameronrye/gopher-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Fgopher-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Fgopher-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Fgopher-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Fgopher-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cameronrye","download_url":"https://codeload.github.com/cameronrye/gopher-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Fgopher-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278254467,"owners_count":25956600,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gemini","gemini-protocol","gopher","gopher-protocol","mcp","mcp-server"],"created_at":"2025-10-04T02:02:10.452Z","updated_at":"2025-12-30T03:24:02.506Z","avatar_url":"https://github.com/cameronrye.png","language":"Python","funding_links":[],"categories":["پیاده‌سازی‌های سرور","📦 Other","カテゴリ"],"sub_categories":["🔎 \u003ca name=\"search\"\u003e\u003c/a\u003eجستجو و استخراج داده","🕸️ \u003ca name=\"web-scraping--collection\"\u003e\u003c/a\u003eWebスクレイピング・収集"],"readme":"# Gopher \u0026 Gemini MCP Server\n\n[![CI](https://github.com/cameronrye/gopher-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/cameronrye/gopher-mcp/actions/workflows/ci.yml)\n[![Documentation](https://github.com/cameronrye/gopher-mcp/actions/workflows/docs.yml/badge.svg)](https://github.com/cameronrye/gopher-mcp/actions/workflows/docs.yml)\n[![PyPI version](https://badge.fury.io/py/gopher-mcp.svg)](https://badge.fury.io/py/gopher-mcp)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![codecov](https://codecov.io/gh/cameronrye/gopher-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/cameronrye/gopher-mcp)\n[![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)\n[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)\n[![Downloads](https://pepy.tech/badge/gopher-mcp)](https://pepy.tech/project/gopher-mcp)\n\nA modern, cross-platform [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants to\nbrowse and interact with both [Gopher protocol](\u003chttps://en.wikipedia.org/wiki/Gopher_(protocol)\u003e) and\n[Gemini protocol](https://geminiprotocol.net/) resources safely and efficiently.\n\n## Overview\n\nThe Gopher \u0026 Gemini MCP Server bridges vintage and modern alternative internet protocols with AI assistants, allowing LLMs like\nClaude to explore the unique content and communities that thrive on both Gopherspace and Geminispace. Built with FastMCP and\nmodern Python practices, it provides secure, efficient gateways to these distinctive internet protocols.\n\n**Key Benefits:**\n\n- **Discover alternative internet content** - Access unique resources on both Gopher and Gemini protocols\n- **Safe exploration** - Built-in security safeguards, TLS encryption, and content filtering\n- **Modern implementation** - Uses FastMCP framework with async/await patterns\n- **Developer-friendly** - Comprehensive testing, type hints, and documentation\n- **Advanced security** - TOFU certificate validation and client certificate support for Gemini\n\n## Features\n\n- **Dual Protocol Support**: `gopher_fetch` and `gemini_fetch` tools for comprehensive protocol coverage\n- **Comprehensive Gopher Support**: Handles menus (type 1), text files (type 0), search servers (type 7), and binary files\n- **Full Gemini Implementation**: Native gemtext parsing, TLS security, and status code handling\n- **Advanced Security**: TOFU certificate validation, client certificates, and secure TLS connections\n- **Safety First**: Built-in timeouts, size limits, input sanitization, and host allowlists\n- **LLM-Optimized**: Returns structured JSON responses designed for AI consumption\n- **Cross-Platform**: Works seamlessly on Windows, macOS, and Linux\n- **Modern Development**: Full type checking, linting, testing, and CI/CD pipeline\n- **High Performance**: Async/await patterns with intelligent caching\n\n## Documentation\n\nComplete documentation is available at **[cameronrye.github.io/gopher-mcp](https://cameronrye.github.io/gopher-mcp)**\n\n- [Installation Guide](https://cameronrye.github.io/gopher-mcp/installation/)\n- [API Reference](https://cameronrye.github.io/gopher-mcp/api-reference/)\n- [Advanced Features](https://cameronrye.github.io/gopher-mcp/advanced-features/)\n- [AI Assistant Guide](https://cameronrye.github.io/gopher-mcp/ai-assistant-guide/)\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** - [Download here](https://www.python.org/downloads/)\n- **uv package manager** - [Install uv](https://docs.astral.sh/uv/getting-started/installation/)\n\n### Installation\n\n#### Option 1: Development Installation (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/cameronrye/gopher-mcp.git\ncd gopher-mcp\n\n# Set up development environment\n./scripts/dev-setup.sh  # Unix/macOS\n# or\nscripts\\dev-setup.bat   # Windows\n\n# Run the server\nuv run task serve\n```\n\n#### Option 2: PyPI Installation\n\n```bash\n# Install from PyPI (recommended for end users)\npip install gopher-mcp\n\n# Or with uv\nuv add gopher-mcp\n```\n\n#### Option 3: Development Installation\n\n```bash\n# Install directly from GitHub\nuv add git+https://github.com/cameronrye/gopher-mcp.git\n\n# Or install in development mode\ngit clone https://github.com/cameronrye/gopher-mcp.git\ncd gopher-mcp\nuv sync --all-extras\n```\n\n### Claude Desktop Integration\n\nAdd to your `claude_desktop_config.json`:\n\n**Unix/macOS/Linux:**\n\n```json\n{\n  \"mcpServers\": {\n    \"gopher\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/gopher-mcp\", \"run\", \"task\", \"serve\"],\n      \"env\": {\n        \"MAX_RESPONSE_SIZE\": \"1048576\",\n        \"TIMEOUT_SECONDS\": \"30\"\n      }\n    }\n  }\n}\n```\n\n**Windows:**\n\n```json\n{\n  \"mcpServers\": {\n    \"gopher\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"C:\\\\path\\\\to\\\\gopher-mcp\",\n        \"run\",\n        \"task\",\n        \"serve\"\n      ],\n      \"env\": {\n        \"MAX_RESPONSE_SIZE\": \"1048576\",\n        \"TIMEOUT_SECONDS\": \"30\"\n      }\n    }\n  }\n}\n```\n\n## Cross-Platform Development\n\nThis project includes a **unified Python-based task management system** that works across all platforms:\n\n### Recommended (All Platforms)\n\n```bash\npython task.py \u003ccommand\u003e    # Unified Python task runner (recommended)\n```\n\n### Alternative Options\n\n```bash\n# Unix/macOS/Linux\nmake \u003ccommand\u003e              # Traditional make (delegates to task.py)\n\n# Universal fallback\nuv run task \u003ccommand\u003e       # Direct taskipy usage\n```\n\n### Available Commands\n\n| Command            | Description                    |\n| ------------------ | ------------------------------ |\n| `dev-setup`        | Set up development environment |\n| `install-hooks`    | Install pre-commit hooks       |\n| `lint`             | Run ruff linting               |\n| `format`           | Format code with ruff          |\n| `typecheck`        | Run mypy type checking         |\n| `quality`          | Run all quality checks         |\n| `check`            | Run lint + typecheck           |\n| `test`             | Run all tests                  |\n| `test-cov`         | Run tests with coverage        |\n| `test-unit`        | Run unit tests only            |\n| `test-integration` | Run integration tests          |\n| `serve`            | Run MCP server (stdio)         |\n| `serve-http`       | Run MCP server (HTTP)          |\n| `docs-serve`       | Serve docs locally             |\n| `docs-build`       | Build documentation            |\n| `clean`            | Clean build artifacts          |\n| `ci`               | Run CI pipeline locally        |\n\n## Usage\n\nThe server provides two powerful MCP tools for exploring alternative internet protocols:\n\n### `gopher_fetch` Tool\n\nFetches Gopher menus, text files, or metadata by URL with comprehensive error handling and security safeguards.\n\n**Parameters:**\n\n- `url` (string, required): Full Gopher URL (e.g., `gopher://gopher.floodgap.com/1/`)\n\n**Response Types:**\n\n- **MenuResult**: For Gopher menus (type 1) and search results (type 7)\n  - Contains structured menu items with type, display text, selector, host, and port\n- **TextResult**: For text files (type 0)\n  - Returns the full text content with metadata\n- **BinaryResult**: Metadata only for binary files (types 4, 5, 6, 9, g, I)\n  - Provides file information without downloading binary content\n- **ErrorResult**: For errors or unsupported content\n  - Includes detailed error messages and troubleshooting hints\n\n### `gemini_fetch` Tool\n\nFetches Gemini content with full TLS security, TOFU certificate validation, and native gemtext parsing.\n\n**Parameters:**\n\n- `url` (string, required): Full Gemini URL (e.g., `gemini://geminiprotocol.net/`)\n\n**Response Types:**\n\n- **GeminiGemtextResult**: For gemtext content (text/gemini)\n  - Parsed gemtext document with structured lines, links, and headings\n- **GeminiSuccessResult**: For other text and binary content\n  - Raw content with MIME type information\n- **GeminiInputResult**: For input requests (status 10-11)\n  - Prompts for user input with optional sensitive flag\n- **GeminiRedirectResult**: For redirects (status 30-31)\n  - New URL for temporary or permanent redirects\n- **GeminiErrorResult**: For errors (status 40-69)\n  - Detailed error information with status codes\n- **GeminiCertificateResult**: For certificate requests (status 60-69)\n  - Certificate requirement information\n\n### Example URLs to Try\n\n#### Gopher Protocol\n\n```bash\n# Classic Gopher menu\ngopher://gopher.floodgap.com/1/\n\n# Gopher news and information\ngopher://gopher.floodgap.com/1/gopher\n\n# Search example (type 7)\ngopher://gopher.floodgap.com/7/v2/vs\n\n# Text file example\ngopher://gopher.floodgap.com/0/gopher/welcome\n```\n\n#### Gemini Protocol\n\n```bash\n# Gemini protocol homepage\ngemini://geminiprotocol.net/\n\n# Gemini software directory\ngemini://geminiprotocol.net/software/\n\n# Example personal gemlog\ngemini://warmedal.se/~antenna/\n\n# Gemini search aggregator\ngemini://kennedy.gemi.dev/\n```\n\n### Example AI Interactions\n\nOnce configured, you can ask Claude:\n\n**Gopher Exploration:**\n\n- _\"Browse the main Gopher menu at gopher.floodgap.com\"_\n- _\"Search for 'python' on the Veronica-2 search server\"_\n- _\"Show me the welcome text from Floodgap's Gopher server\"_\n- _\"What's available in the Gopher community directory?\"_\n\n**Gemini Exploration:**\n\n- _\"Fetch the Gemini protocol homepage\"_\n- _\"Show me the software directory on geminiprotocol.net\"_\n- _\"Browse the latest posts from a gemlog\"_\n- _\"What's the difference between Gopher and Gemini protocols?\"_\n\n## Development\n\n### Project Structure\n\n```text\ngopher-mcp/\n├── src/gopher_mcp/          # Main package\n│   ├── __init__.py          # Package initialization\n│   ├── server.py            # FastMCP server implementation\n│   ├── gopher_client.py     # Gopher protocol client\n│   ├── models.py            # Pydantic data models\n│   ├── tools.py             # MCP tool definitions\n│   └── utils.py             # Utility functions\n├── tests/                   # Comprehensive test suite\n│   ├── test_server.py       # Server tests\n│   ├── test_gopher_client.py # Client tests\n│   └── test_integration.py  # Integration tests\n├── docs/                    # MkDocs documentation\n├── scripts/                 # Development scripts\n├── .github/workflows/       # CI/CD pipelines\n├── Makefile                 # Unix/macOS task runner\n├── task.bat                 # Windows task runner\n└── pyproject.toml           # Modern Python project config\n```\n\n### Development Workflow\n\n1. **Setup**: `uv run task dev-setup` - Install dependencies and pre-commit hooks\n2. **Code**: Make your changes with full IDE support (type hints, linting)\n3. **Quality**: `uv run task quality` - Run all quality checks (lint + typecheck + test)\n4. **Test**: `uv run task test-cov` - Run tests with coverage reporting\n5. **Commit**: Pre-commit hooks ensure code quality automatically\n\n### Testing\n\n```bash\n# Run all tests\nuv run task test\n\n# Run with coverage\nuv run task test-cov\n\n# Run specific test types\nuv run task test-unit\nuv run task test-integration\n\n# Run tests in watch mode during development\nuv run pytest --watch\n```\n\n## Configuration\n\nThe server can be configured through environment variables for both protocols:\n\n### Gopher Configuration\n\n| Variable                   | Description                    | Default         | Example                |\n| -------------------------- | ------------------------------ | --------------- | ---------------------- |\n| `GOPHER_MAX_RESPONSE_SIZE` | Maximum response size in bytes | `1048576` (1MB) | `2097152`              |\n| `GOPHER_TIMEOUT_SECONDS`   | Request timeout in seconds     | `30`            | `60`                   |\n| `GOPHER_CACHE_ENABLED`     | Enable response caching        | `true`          | `false`                |\n| `GOPHER_CACHE_TTL_SECONDS` | Cache time-to-live in seconds  | `300`           | `600`                  |\n| `GOPHER_ALLOWED_HOSTS`     | Comma-separated allowed hosts  | `None` (all)    | `example.com,test.com` |\n\n### Gemini Configuration\n\n| Variable                      | Description                        | Default         | Example                |\n| ----------------------------- | ---------------------------------- | --------------- | ---------------------- |\n| `GEMINI_MAX_RESPONSE_SIZE`    | Maximum response size in bytes     | `1048576` (1MB) | `2097152`              |\n| `GEMINI_TIMEOUT_SECONDS`      | Request timeout in seconds         | `30`            | `60`                   |\n| `GEMINI_CACHE_ENABLED`        | Enable response caching            | `true`          | `false`                |\n| `GEMINI_CACHE_TTL_SECONDS`    | Cache time-to-live in seconds      | `300`           | `600`                  |\n| `GEMINI_ALLOWED_HOSTS`        | Comma-separated allowed hosts      | `None` (all)    | `example.org,test.org` |\n| `GEMINI_TOFU_ENABLED`         | Enable TOFU certificate validation | `true`          | `false`                |\n| `GEMINI_CLIENT_CERTS_ENABLED` | Enable client certificate support  | `true`          | `false`                |\n\n### Example Configuration\n\n```bash\n# Gopher settings\nexport GOPHER_MAX_RESPONSE_SIZE=2097152\nexport GOPHER_TIMEOUT_SECONDS=60\nexport GOPHER_CACHE_ENABLED=true\nexport GOPHER_ALLOWED_HOSTS=\"gopher.floodgap.com,gopher.quux.org\"\n\n# Gemini settings\nexport GEMINI_MAX_RESPONSE_SIZE=2097152\nexport GEMINI_TIMEOUT_SECONDS=60\nexport GEMINI_TOFU_ENABLED=true\nexport GEMINI_CLIENT_CERTS_ENABLED=true\nexport GEMINI_ALLOWED_HOSTS=\"geminiprotocol.net,warmedal.se\"\n\n# Run with custom config\nuv run task serve\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Quick Contribution Steps\n\n1. **Fork** the repository on GitHub\n2. **Clone** your fork: `git clone https://github.com/your-username/gopher-mcp.git`\n3. **Setup** development environment: `uv run task dev-setup`\n4. **Create** a feature branch: `git checkout -b feature/amazing-feature`\n5. **Make** your changes with tests\n6. **Quality** check: `uv run task quality`\n7. **Commit** your changes: `git commit -m 'Add amazing feature'`\n8. **Push** to your fork: `git push origin feature/amazing-feature`\n9. **Submit** a pull request with a clear description\n\n### Development Standards\n\n- **Type hints** for all functions and methods\n- **Comprehensive tests** with \u003e90% coverage\n- **Documentation** for all public APIs\n- **Security** considerations for all network operations\n- **Cross-platform** compatibility (Windows, macOS, Linux)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- **[Model Context Protocol](https://modelcontextprotocol.io/)** by Anthropic - The foundation that makes this integration possible\n- **[FastMCP](https://github.com/jlowin/fastmcp)** - High-level Python framework for building MCP servers\n- **[Pituophis](https://github.com/dotcomboom/pituophis)** - Excellent Python Gopher client library\n- **The Gopher Protocol Community** - Keeping the spirit of the early internet alive\n\n## Related Projects\n\n- [Model Context Protocol Servers](https://github.com/modelcontextprotocol/servers) - Official MCP server implementations\n- [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) - Curated list of MCP servers\n- [Claude Desktop](https://claude.ai/download) - AI assistant that supports MCP\n\n## Support\n\n- **Bug Reports**: [GitHub Issues](https://github.com/cameronrye/gopher-mcp/issues)\n- **Feature Requests**: [GitHub Discussions](https://github.com/cameronrye/gopher-mcp/discussions)\n- **Documentation**: [Project Docs](https://cameronrye.github.io/gopher-mcp/)\n- **Community**: [MCP Discord](https://discord.gg/modelcontextprotocol)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nMade with ❤️ by [Cameron Rye](https://rye.dev/)\n\n[Star this project](https://github.com/cameronrye/gopher-mcp) if you find it useful!\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcameronrye%2Fgopher-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcameronrye%2Fgopher-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcameronrye%2Fgopher-mcp/lists"}