github-pro-mcp 0.0.2 → 0.0.4

package/LICENSE

@@ -0,0 +1,76 @@
+GitHub Pro MCP Proprietary License
+
+Copyright (c) 2026 Anant Anand Gupta. All rights reserved.
+
+This software is proprietary. It is licensed, not sold.
+
+1. Grant of License
+
+Subject to the terms of this License, you are granted a limited, non-exclusive,
+non-transferable, non-sublicensable and revocable license to install and use
+the software for your own personal use or for internal use within your
+organization. You may make a reasonable number of copies for backup purposes,
+provided every copy is subject to this License.
+
+2. Restrictions
+
+You may not:
+
+  a. modify, adapt, translate, or create derivative works of the software;
+  b. redistribute, publish, sublicense, sell, resell, rent, lease, lend, or
+     otherwise make the software available to any third party;
+  c. make the software available as part of a product or service offered to
+     others, whether for payment or free of charge;
+  d. remove, obscure, or alter any copyright, trademark, or other proprietary
+     notice in the software;
+  e. reverse engineer, decompile, disassemble, or otherwise attempt to derive
+     the source code of the software, except to the extent that applicable law
+     expressly permits despite this limitation;
+  f. use the software to develop or operate a product or service that competes
+     with it.
+
+3. No Source Code
+
+This License does not grant any right to the source code of the software. No
+source code is published or made available, and the copyright holder has no
+obligation to provide it.
+
+4. Ownership
+
+All right, title, and interest in and to the software, including all
+intellectual property rights, remain with the copyright holder. Nothing in
+this License transfers ownership of the software to you.
+
+5. Third-Party Components
+
+The software depends on third-party packages that are distributed under their
+own licenses. Those licenses continue to apply to those components, and nothing
+in this License limits your rights under them.
+
+6. No Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. THE COPYRIGHT
+HOLDER DOES NOT WARRANT THAT THE SOFTWARE WILL BE UNINTERRUPTED, ERROR-FREE,
+OR FIT FOR ANY PARTICULAR PURPOSE.
+
+7. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+8. Termination
+
+This License terminates automatically if you breach any of its terms. Upon
+termination you must stop using the software and delete all copies in your
+possession or control. Sections 3, 4, 6, 7 and 9 survive termination.
+
+9. Acceptance
+
+By installing, copying, or using the software, you accept this License. If you
+do not accept it, do not install or use the software.
+
+Licensing enquiries: see the repository URL in package.json.

package/README.md

@@ -3,18 +3,71 @@
 [![npm version](https://img.shields.io/npm/v/github-pro-mcp)](https://www.npmjs.com/package/github-pro-mcp)
 [![Docker image](https://img.shields.io/docker/v/anantanandgupta/github-pro-mcp)](https://hub.docker.com/r/anantanandgupta/github-pro-mcp)
 
-An MCP (Model Context Protocol) server providing comprehensive GitHub API access via hybrid REST + GraphQL — **34 tools across 8 domains**.
-
-## Features
-
-- **34 Tools** — issues, pull requests, repositories, projects v2, labels, organizations, file operations, server info
-- **Hybrid API** — REST for CRUD/search, GraphQL for cursor pagination and composite queries
-- **Resilient by Default** — automatic retry with exponential backoff + jitter, circuit breaker for API outages, proactive rate limit management
-- **Structured Logging** — multi-level (error/warn/info/debug) stderr output
-- **Owner/Repo Pinning** — lock the server to a specific owner or repository as a safety guardrail
+GitHub Pro MCP gives Claude Code, Cursor, Copilot, opencode and any MCP host a
+complete GitHub toolkit: **34 tools** for issues, pull requests, files, projects,
+labels and organizations.
+
+Read-only mode is the default. The server registers 19 read tools and keeps the
+15 write tools out of the agent's context. Set
+`GITHUB_MCP_ENABLE_WRITES=true` to load the full set.
+
+It runs locally, connects to your host over stdio, and calls the GitHub API
+directly with your own token. There is no intermediary service.
+
+New to MCP? It is the open protocol that lets a host connect a model to tools:
+https://modelcontextprotocol.io/
+
+**Documentation, installation guides, permissions and token generator:**
+https://mcp.anantanandgupta.net/
+
+## What you can do
+
+- **Triage issues** - read, search, comment, label, close, reopen and manage
+  sub-issues.
+- **Review pull requests** - read details, commits and reviews, create pull
+  requests and merge them.
+- **Work with files** - read, create, update and delete files, and search code
+  across repositories.
+- **Organize work** - set Priority, Effort and dates, and move items through
+  Projects v2.
+- **Find your way around** - list every repository an organization owns, and
+  search organizations and code.
+
+Ask in plain language. The agent chooses the tools, and the server handles the
+API details.
+
+## Why this server
+
+- **34 tools across 8 domains.** Issues, pull requests, repositories, projects,
+  labels, organizations, file operations and server info.
+- **Read-only by default.** 19 tools, no write surface. Enable writes explicitly.
+- **Built for the common path.** The daily loop is small: read an issue, review a pull
+  request, change a file, update a project field. The long tail stays out of the
+  agent's context until you need it.
+- **Organization-aware.** `owner_list_repository` lists every repository in an
+  organization.
+- **Built for real API conditions.** Retries with backoff, rate-limit handling
+  and a circuit breaker for repeated failures. The defaults work; there is
+  nothing to tune.
+- **Guardrails.** Pin the server to one owner or repository with
+  `GITHUB_OWNER` / `GITHUB_REPO`, and mismatched calls are rejected.
+- **Guided token setup.** The generator builds a pre-filled fine-grained token
+  with a read-only or read-write preset.
+- **Any MCP host.** A standard stdio server. Works with opencode, Claude
+  Desktop, Cursor, VS Code and anything else that speaks MCP.
+- **No runtime dependencies.** The npm package ships one bundled file, so
+  installing it does not pull a dependency tree.
+- **GitHub Enterprise Server.** Point `GITHUB_HOST` at your GHES API.
+
+If your work is mostly Actions, security scanning, notifications, discussions,
+gists, governance or Copilot, use the official GitHub MCP server. GitHub Pro MCP
+is built for the daily issue, pull request, file and project loop.
 
 ## Installation
 
+Requires Node.js 22 or newer for the npm package. The Docker image includes
+Node.js.
+
 ### npm
 
 ```bash
@@ -22,94 +75,149 @@ An MCP (Model Context Protocol) server providing comprehensive GitHub API access
 npm install -g github-pro-mcp
 
 # Or run directly without installing
-npx github-pro-mcp
+npx -y github-pro-mcp
 ```
 
 ### Docker
 
-Multi-arch images for `linux/amd64` and `linux/arm64`:
+Multi-arch images are published for `linux/amd64` and `linux/arm64`.
 
 ```bash
 docker pull anantanandgupta/github-pro-mcp
 ```
 
-## Quick Start
+## Quick start
 
-Set your GitHub token and run:
+1. Create a token with the generator:
+   https://mcp.anantanandgupta.net/github-pro-mcp/token/
+2. Install the server with npm or Docker.
+3. Add it to your MCP host and restart the host.
+4. Verify with the `auth_get_current_login` tool.
 
-```bash
-export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
-github-pro-mcp
-```
+By default the server is read-only and registers 19 tools. To enable issue,
+pull request, file, label and project writes, set
+`GITHUB_MCP_ENABLE_WRITES=true` in the host environment.
 
-Or with Docker:
+### Create a token
 
-```bash
-docker run -i --rm \
-  -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here \
-  anantanandgupta/github-pro-mcp
-```
+Use a fine-grained personal access token. The generator builds a pre-filled
+GitHub page with the right checkboxes:
 
-## Configuration
+- **Read-only preset:** Metadata read, Contents read, Issues read, Pull requests
+  read, Issue fields read, Issue types read, Projects read.
+- **Read-write preset:** Metadata read, Contents write, Issues write, Pull
+  requests write, Issue fields write, Issue types read, Projects write.
 
-### Required
+Merging a pull request also requires Contents write. If the repository belongs
+to an organization that requires approval, request it while creating the token.
 
-| Variable | Description |
-|----------|-------------|
-| `GITHUB_PERSONAL_ACCESS_TOKEN` | GitHub PAT with appropriate scopes |
+The full per-tool permission table is at
+https://mcp.anantanandgupta.net/github-pro-mcp/permissions/
 
-### Optional
+The read-only preset pairs with the default read-only mode. The read-write
+preset requires `GITHUB_MCP_ENABLE_WRITES=true` in the host environment.
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `GITHUB_HOST` | — | For GHES: `https://{hostname}/api/v3` |
-| `GITHUB_OWNER` | — | Pin server to a single owner (rejects mismatched calls) |
-| `GITHUB_REPO` | — | Pin server to a single repository (rejects mismatched calls) |
-| `GITHUB_RETRY_MAX_ATTEMPTS` | `3` | Max retries for transient errors |
-| `GITHUB_RETRY_BACKOFF_MS` | `1000` | Initial retry backoff (ms) |
-| `GITHUB_CIRCUIT_BREAKER_THRESHOLD` | `5` | Failures before circuit opens |
-| `GITHUB_CIRCUIT_BREAKER_RESET_MS` | `30000` | Circuit recovery timeout (ms) |
-| `GITHUB_RETRY_BACKOFF_FACTOR` | `2` | Exponential backoff multiplier |
-| `GITHUB_OWNER_TYPE_CACHE_MS` | `300000` | Cache TTL for owner type lookups (5 min) |
-| `GITHUB_THROTTLE_ON_RATE_LIMIT` | `retry` | Primary rate limit strategy: `retry` or `queue` |
-| `GITHUB_THROTTLE_ON_SECONDARY_RATE_LIMIT` | `retry` | Secondary rate limit strategy: `retry` or `queue` |
-| `GITHUB_LOG_LEVEL` | `error` | Log level: `error`, `warn`, `info`, `debug` |
-
-## Usage with opencode
-
-Add to your `opencode.json`:
+### Connect opencode
 
-```json
+Add to your opencode config (v2 nests servers under `mcp.servers`):
+
+```jsonc
 {
   "mcp": {
-    "github_pro": {
-      "type": "local",
-      "command": ["node", "path/to/github-pro-mcp/dist/index.js"],
-      "environment": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
+    "servers": {
+      "github_pro": {
+        "type": "local",
+        "command": ["npx", "-y", "github-pro-mcp"],
+        "environment": {
+          "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}",
+          "GITHUB_MCP_ENABLE_WRITES": "true"
+        }
       }
     }
   }
 }
 ```
 
-For Docker-based usage:
+`{env:GITHUB_TOKEN}` reads that variable from the environment opencode starts
+in. Use a literal token instead if you prefer. Remove
+`GITHUB_MCP_ENABLE_WRITES` to stay read-only.
+
+### Connect Claude Desktop
+
+Edit `claude_desktop_config.json` and restart Claude Desktop:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "github-pro-mcp"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_...",
+        "GITHUB_MCP_ENABLE_WRITES": "true"
+      }
+    }
+  }
+}
+```
+
+### Connect Cursor or VS Code
+
+Both support stdio MCP servers. The configuration is the same command and token
+as above; only the file location differs. Exact snippets are in the
+installation guide:
+
+https://mcp.anantanandgupta.net/github-pro-mcp/install/
+
+### Use Docker with opencode
+
+```jsonc
 {
   "mcp": {
-    "github_pro": {
-      "type": "local",
-      "command": ["docker", "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "anantanandgupta/github-pro-mcp"],
-      "environment": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
+    "servers": {
+      "github_pro": {
+        "type": "local",
+        "command": ["docker", "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "-e", "GITHUB_MCP_ENABLE_WRITES", "anantanandgupta/github-pro-mcp"],
+        "environment": {
+          "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}",
+          "GITHUB_MCP_ENABLE_WRITES": "true"
+        }
       }
     }
   }
 }
 ```
 
-## Tool Reference
+The same `docker run` command works as the server command in other hosts.
+
+## Configuration
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_PERSONAL_ACCESS_TOKEN` | GitHub personal access token. Fine-grained is recommended. |
+
+### Optional
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_HOST` | GitHub Enterprise Server API, for example `https://github.example.com/api/v3` |
+| `GITHUB_OWNER` | Pin the server to a single owner and reject mismatched calls |
+| `GITHUB_REPO` | Pin the server to a single repository and reject mismatched calls |
+| `GITHUB_MCP_ENABLE_WRITES` | Set to `true`, `1`, `yes` or `on` to register the 15 write tools. Default `false` |
+
+Retries, rate limiting and logging have sensible defaults. You do not need to
+tune them for normal use.
+
+## Tools
+
+34 tools across 8 domains. Read-only mode registers 19 of them; the other 15
+are write tools. Tool names appear in your host's tool list after the server
+starts.
 
 | Domain | Tools | Count |
 |--------|-------|-------|
@@ -123,16 +231,35 @@ For Docker-based usage:
 | **Server Info** | `server_info` | 1 |
 | **Total** | | **34** |
 
-## FAQ / Troubleshooting
+Task-based examples and the prompts they respond to are at
+https://mcp.anantanandgupta.net/github-pro-mcp/tools/
+
+A measured comparison with the official GitHub MCP server is at
+https://mcp.anantanandgupta.net/github-pro-mcp/compare/
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---------|--------------|
+| `401` | Token expired, revoked or mistyped |
+| `403` | Missing permission, organization approval, or SSO not authorized |
+| `404` | The resource does not exist, or the token cannot see it |
+| `429` | Rate limited. The server retries; wait if it persists |
+| No tools appear in the host | The host was not restarted, or the server failed to start |
+| Server exits immediately | `GITHUB_PERSONAL_ACCESS_TOKEN` is not set in the host's environment |
+| Write tool not in the list | `GITHUB_MCP_ENABLE_WRITES` is not set to `true` |
+
+## Support
 
-| Error | Likely Cause |
-|-------|-------------|
-| `401` | Token expired or invalid |
-| `403` | Missing OAuth scopes or SSO |
-| `404` | Resource doesn't exist or no access |
-| `429` | Rate limited — wait and retry |
-| Circuit breaker open | GitHub API returning repeated errors — auto-recovers in 30s |
+- **Documentation:** https://mcp.anantanandgupta.net/
+- **Issues and feature requests:** https://github.com/anantanandgupta/mcp-servers/issues
+- **npm:** https://www.npmjs.com/package/github-pro-mcp
+- **Docker:** https://hub.docker.com/r/anantanandgupta/github-pro-mcp
 
 ## License
 
-ISC
+Proprietary. Free to install and use, including for internal business purposes.
+Modification, redistribution, sublicensing and reverse engineering are not
+permitted. See the
+[license](https://github.com/anantanandgupta/mcp-servers/blob/main/github-pro-mcp/LICENSE)
+for the full terms.