├── LICENSE ├── CLAUDE.md ├── .github └── copilot-instructions.md ├── .cursor └── rules │ └── rtfmbro.mdc └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 Marc Krenn 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /CLAUDE.md: -------------------------------------------------------------------------------- 1 | # Instructions for Package Documentation 2 | ## Package Documentation Policy 3 | 4 | * Before using any package, module, or library, ALWAYS consult its documentation — your internal knowledge may be outdated and could cause errors or failures. 5 | * Don't assume anything about the package's functionality, usage, or configuration without verifying it against the official documentation. 6 | * If you are unsure about a user's request that may involve a package, module, or library, **ALWAYS** refer to the documentation first or ask the user to provide the package name and version. 7 | 8 | ### Workflow 9 | 0. Don't immediately lookup the user's original codebase. 10 | 1. First, **Identify** the package name and the EXACT pinned version (eg. "==1.0.5") from the project’s lock file (eg. uv.lock, bun.lock). 11 | 2. Using this information **fetch documentation** by executing one of the provided tools: 12 | - `get_readme` 13 | - `get_documentation_tree` 14 | - `read_files` 15 | - `search_github_repositories` - Search for Github packages and repositories by topic, language, or keywords. Note, sometimes the documentation is located in a separate repository (like `tailwindlabs/tailwindcss.com`). Use the repo owner to search for the repo containing the documentation. 16 | 3. **Review** the documentation carefully to understand: 17 | - Core functionality 18 | - Usage patterns 19 | - Any caveats or special instructions 20 | 4. **Reference examples** from the documentation to guide your implementation. 21 | 22 | **Ecosystem Selection:** 23 | - Use `pypi` for Python packages 24 | - Use `npm` for Node.js packages 25 | - Use `spm` for Swift packages 26 | - Use `gh` only as a fallback for languages not supported by the above registries (package name must be in 'owner/repo' format) or if you're unsure about the package's ecosystem. Also use `gh` when you don't find the package in the lock file. -------------------------------------------------------------------------------- /.github/copilot-instructions.md: -------------------------------------------------------------------------------- 1 | # Copilot Instructions for Package Documentation 2 | ## Package Documentation Policy 3 | 4 | * Before using any package, module, or library, ALWAYS consult its documentation — your internal knowledge may be outdated and could cause errors or failures. 5 | * Don't assume anything about the package's functionality, usage, or configuration without verifying it against the official documentation. 6 | * If you are unsure about a user's request that may involve a package, module, or library, **ALWAYS** refer to the documentation first or ask the user to provide the package name and version. 7 | 8 | ### Workflow 9 | 0. Don't immediately lookup the user's original codebase. 10 | 1. First, **Identify** the package name and the EXACT pinned version (eg. "==1.0.5") from the project’s lock file (eg. uv.lock, bun.lock). 11 | 2. Using this information **fetch documentation** by executing one of the provided tools: 12 | - `get_readme` 13 | - `get_documentation_tree` 14 | - `read_files` 15 | - `search_github_repositories` - Search for Github packages and repositories by topic, language, or keywords. Note, sometimes the documentation is located in a separate repository (like `tailwindlabs/tailwindcss.com`). Use the repo owner to search for the repo containing the documentation. 16 | 3. **Review** the documentation carefully to understand: 17 | - Core functionality 18 | - Usage patterns 19 | - Any caveats or special instructions 20 | 4. **Reference examples** from the documentation to guide your implementation. 21 | 22 | **Ecosystem Selection:** 23 | - Use `pypi` for Python packages 24 | - Use `npm` for Node.js packages 25 | - Use `spm` for Swift packages 26 | - Use `gh` only as a fallback for languages not supported by the above registries (package name must be in 'owner/repo' format) or if you're unsure about the package's ecosystem. Also use `gh` when you don't find the package in the lock file. -------------------------------------------------------------------------------- /.cursor/rules/rtfmbro.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: rtfmbro Package Documentation Policy 3 | globs: 4 | alwaysApply: true 5 | --- 6 | 7 | # Cursor Instructions for Package Documentation 8 | ## Package Documentation Policy 9 | 10 | * Before using any package, module, or library, ALWAYS consult its documentation — your internal knowledge may be outdated and could cause errors or failures. 11 | * Don't assume anything about the package's functionality, usage, or configuration without verifying it against the official documentation. 12 | * If you are unsure about a user's request that may involve a package, module, or library, **ALWAYS** refer to the documentation first or ask the user to provide the package name and version. 13 | 14 | ### Workflow 15 | 0. Don't immediately lookup the user's original codebase. 16 | 1. First, **Identify** the package name and the EXACT pinned version (eg. "==1.0.5") from the project’s lock file (eg. uv.lock, bun.lock). 17 | 2. Using this information **fetch documentation** by executing one of the provided tools: 18 | - `get_readme` 19 | - `get_documentation_tree` 20 | - `read_files` 21 | - `search_github_repositories` - Search for Github packages and repositories by topic, language, or keywords. Note, sometimes the documentation is located in a separate repository (like `tailwindlabs/tailwindcss.com`). Use the repo owner to search for the repo containing the documentation. 22 | 3. **Review** the documentation carefully to understand: 23 | - Core functionality 24 | - Usage patterns 25 | - Any caveats or special instructions 26 | 4. **Reference examples** from the documentation to guide your implementation. 27 | 28 | **Ecosystem Selection:** 29 | - Use `pypi` for Python packages 30 | - Use `npm` for Node.js packages 31 | - Use `spm` for Swift packages 32 | - Use `gh` only as a fallback for languages not supported by the above registries (package name must be in 'owner/repo' format) or if you're unsure about the package's ecosystem. Also use `gh` when you don't find the package in the lock file. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # rtfmbro-mcp 2 | 3 | > rtfmbro provides always-up-to-date, version-specific package documentation as context for coding agents. An alternative to [context7](https://github.com/upstash/context7). 4 | 5 | https://github.com/user-attachments/assets/dbe0b3b4-a42c-4e91-8bcd-a94d430ef0b8 6 | 7 | Demonstration of rtfmbro in use, fetching a specific version (3.1.1) of Flask's [readme](https://github.com/pallets/flask/blob/3.1.1/README.md) and [docs](https://github.com/pallets/flask/tree/3.1.1/docs). 8 | 9 | ## Overview 10 | 11 | rtfmbro is a Model Context Protocol (MCP) server that provides real-time, version-aware documentation fetching for packages across multiple ecosystems. It bridges the gap between AI agents and accurate, up-to-date package documentation by fetching docs directly from GitHub repositories at the exact version your project uses. 12 | 13 | ## Supported Ecosystems 14 | 15 | | Ecosystem | Registry | Status | 16 | |-----------|----------|--------| 17 | | **Python** | PyPI | ✅ Full Support | 18 | | **Node.js** | npm | ✅ Full Support | 19 | | **Swift** | SPM | 🚧 Alpha | 20 | | **GitHub** | Direct | ⚠️ Fallback | 21 | 22 | ## Why rtfmbro? 23 | 24 | ### The Problem 25 | - **Stale Documentation**: AI models often rely on outdated training data about packages 26 | - **Missing Context**: Source code in `node_modules` etc. lacks high-level documentation, browsing it is usually token-consuming and inefficient 27 | - **Version Mismatches**: Generic documentation doesn't match your specific package version, especially for legacy projects or brand new packages 28 | 29 | ### The Solution 30 | rtfmbro tries to solve these issues by: 31 | 32 | 1. **Version-Precise Fetching**: Retrieves documentation from the exact git tag/commit that matches your lockfile 33 | 2. **Comprehensive Coverage**: Extracts all documentation files (`.md`, `.mdx`, `.txt`, `.rst`, `.html`) from the repository 34 | 3. **Intelligent Caching**: SHA-based currency checking ensures docs stay fresh without unnecessary re-fetching 35 | 4. **Agent Integration**: Seamlessly integrates with AI coding assistants via the Model Context Protocol 36 | 5. **Great DX**: Zero seting up for developers, just add the server to your MCP configuration, instructions and start fetching docs 37 | 38 | ### MCP Tools 39 | 40 | The server exposes four primary tools to AI agents: 41 | 42 | | Tool | Purpose | Parameters | Returns | 43 | |------|---------|------------|---------| 44 | | `get_readme` | Fetches and returns the README file for a specific package version | `package`, `version`, `ecosystem` | README content as string | 45 | | `get_documentation_tree` | Generates a comprehensive folder structure of all documentation files | `package`, `version`, `ecosystem` | Tree structure as string | 46 | | `read_files` | Reads specific documentation files with optional line range slicing | `package`, `version`, `ecosystem`, `requests[]` | Dictionary mapping paths to content | 47 | | `search_github_repositories` | Searches for GitHub repositories using the GitHub Search API | `query`, `sort`, `order`, `per_page` | Formatted repository search results | 48 | 49 | ## Installation & Setup 50 | 51 | ### Quick Start 52 | 53 | #### Claude Code 54 | 55 | ```bash 56 | claude mcp add-json rtfmbro '{ "type": "http", "url": "https://rtfmbro.smolosoft.dev/mcp/" }' 57 | ``` 58 | 59 | #### Claude Desktop / VS Code / etc. 60 | 61 | Add the remote server to your MCP configuration: 62 | 63 | ```json 64 | { 65 | "rtfmbro": { 66 | "type": "http", 67 | "url": "https://rtfmbro.smolosoft.dev/mcp/" 68 | } 69 | } 70 | ``` 71 | 72 | #### Cursor 73 | 74 | [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=rtfmbro&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vcnRmbWJyby5zbW9sb3NvZnQuZGV2L21jcC8ifQ%3D%3D) 75 | 76 | ### Agent Integration 77 | 78 | To truly integrate rtfmbro with your AI coding agent of choice, copy the appropriate meta-instruction file to your project: 79 | 80 | - **GitHub Copilot**: Copy [`.github/copilot-instructions.md`](.github/copilot-instructions.md) to your project 81 | - **Claude Code**: Copy [`CLAUDE.md`](CLAUDE.md) to your project root 82 | - **Cursor**: Copy [`.cursor/rules`](.cursor/rules) to your project root 83 | - **Other agents**: Adapt the instructions from either file above to your agent's format 84 | 85 | ## How It Works 86 | 87 | ### Documentation Workflow 88 | 89 | 1. **Registry Lookup**: Queries the package registry (PyPI, npm, etc.) for metadata 90 | 2. **GitHub Discovery**: Extracts the GitHub repository URL from package metadata 91 | 3. **Version Resolution**: Fetches available git tags and matches them against your semantic version 92 | 4. **Smart Fetching**: Clones the repository at the exact matched tag/commit 93 | 5. **Content Filtering**: Extracts only documentation files, removing source code and build artifacts 94 | 6. **Caching & Currency**: Stores results with SHA-based currency checking for efficient re-access 95 | 96 | ### Caching Strategy 97 | 98 | - **SHA-Based Validation**: Compares current repository commit SHA with cached version 99 | - **Automatic Invalidation**: Re-fetches documentation when new commits are detected 100 | - **Persistent Storage**: Maintains local cache to avoid redundant GitHub API calls 101 | - **Metadata Preservation**: Stores documentation tree structure for fast browsing 102 | 103 | ## Prerequisites 104 | 105 | - Package must be published to a supported registry (PyPI, npm) 106 | - Package metadata must contain a valid GitHub repository link 107 | - Repository must use git tags for version management 108 | - Documentation files must be present in the repository (not just generated sites) 109 | 110 | ## Roadmap 111 | 112 | ### Near Term 113 | - [x] **Ecosystem independent fallback**: Implement a fallback mechanism for unsupported ecosystems 114 | - [ ] **Provide rtfmbro source code**: Open source the server codebase 115 | - [ ] **Public docker image**: Create a public Docker image for easy deployment 116 | - [ ] **Private repo support**: Allow authenticated access to private repositories 117 | - [ ] **Add Tests**: Implement unit and integration tests for core functionality 118 | - [ ] **Enhanced Python Support**: Include pydocs and docstring extraction 119 | - [ ] **Search Capabilities**: Search across documentation corpus 120 | 121 | ### Future Ecosystems / Languages / Registries 122 | - [ ] **Rust** ([crates.io](https://crates.io/)) 123 | - [ ] **Go** ([pkg.go.dev](https://pkg.go.dev/)) 124 | - [ ] **Java/Kotlin** ([Maven Central](https://central.sonatype.com/)) 125 | - [ ] **C#/.NET** ([NuGet](https://www.nuget.org/)) 126 | - [ ] **Ruby** ([RubyGems](https://rubygems.org/)) 127 | 128 | ### Source code hosting and repository support: 129 | - [x] **GitHub**: Support for GitHub repositories 130 | - [ ] **Gitlab**: Support for GitLab repositories 131 | - [ ] **Bitbucket**: Support for Bitbucket repositories 132 | - [ ] **Launchpad**: Support for Launchpad repositories 133 | 134 | ## Known Issues 135 | 136 | - Some packages may have documentation in separate standalone repos 137 | - Large repositories may take a bit of time to clone and process initially 138 | 139 | ## Similar / Additive Projects 140 | 141 | - **[mcp-package-docs](https://github.com/sammcj/mcp-package-docs)**: Another MCP server for package documentation, focusing on documentation extraction, LSP servers, etc. May be a great supplement to rtfmbro. 142 | - **[rust-docs-mcp-server](https://github.com/Govcraft/rust-docs-mcp-server)**: MCP server for Rust documentation, focused on Rust-specific features and documentation formats. 143 | - **[mcp-ragdocs](https://github.com/qpd-v/mcp-ragdocs)**: MCP server for RAG (Retrieval-Augmented Generation) documentation, aimed at improving the documentation experience for AI models. 144 | - **[godoc-mcp](https://github.com/mrjoshuak/godoc-mcp)**: MCP server for Go documentation, providing access to Go package documentation via the Model Context Protocol. 145 | - **[context7](https://github.com/upstash/context7)**: Alternative to rtfmbro 146 | 147 | ### Differences between **context7** and **rtfmbro** 148 | |Aspect|context7|rtfmbro| 149 | |------|--------|-------| 150 | | **Actuality** | Scrapes documentation ahead-of-time at intransparent intervals or upon user trigger. As of writing, the "latest" Next.js docs are already 2 days old.| Fetches documentation just-in-time, ensuring it's always up-to-date. | 151 | | **Version-specific docs** | Theoretically allows scraping older versions (useful for legacy or longtime projects), but the process is complicated, limiting practical availability effectively to latest versions. | Fetches older documentation just-in-time, and always remains current, identical to latest docs. | 152 | | **Search strategy** | Uses either A) optionally token-limited RAG search to filter/preprocess docs which can be hit-or-miss, or B) dumps all content into LLM's context, resulting in excessive token-use. | Employs agentic discovery ([as used by Claude Code itself](https://x.com/pashmerepat/status/1926717705660375463)) | 153 | | **Developer Experience** | Requires explicitly mention of context7 in every prompt. | Operates via defined rules/instructions, auto-selecting appropriate package name/version from lock file ("set and forget"). | 154 | | **Support** | Language/ecosystem independent. | Currently language/ecosystem-specific; planned additional languages/ecosystems and language-independent fallback mechanism soon. | 155 | --------------------------------------------------------------------------------