diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index 9cbd8fd2..9d66b354 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -240,6 +240,36 @@ bash scripts/setup-linkedin-mcp.sh --- +## GitHub (`github-mcp-server`) (optional) + +The official [github/github-mcp-server](https://github.com/github/github-mcp-server) (Go) ships as a pre-built 6.7 MB single binary. With `--toolsets=all` it exposes **79 tools** covering repos, issues, pull requests, gists, workflows, code search, security, projects, notifications, and more. Auth is a GitHub Personal Access Token passed as `GITHUB_PERSONAL_ACCESS_TOKEN`. + +### One-time install + +From the repo root: + +```bash +bash scripts/setup-github-mcp.sh +``` + +The script detects your platform (macOS/Linux × x86_64/arm64), downloads the latest release tarball from GitHub Releases, and installs the binary at `~/.openswarm/bin/github-mcp-server`. Re-running it upgrades to the latest version. + +### Connect from the UI + +1. Create a Personal Access Token at https://github.com/settings/tokens. Fine-grained tokens are recommended; pick the scopes you want the agent to have. +2. Open the **Tools** page in the sidebar. +3. Find the **GitHub** tile and click **Connect GitHub**. +4. Paste the token and confirm. The tile flips to **Connected** and the server is spawned on demand for tool calls. + +### Notes + +* No background daemon. The binary is spawned by OpenSwarm only when an agent invokes a GitHub tool. +* The token is stored locally in OpenSwarm's tool config and passed as an env var to the binary at spawn time. +* To rotate the token, click the **Connected** chip to disconnect, then reconnect with the new value. +* For read-only mode (safer default for unattended agents), edit the tool's `mcp_config.args` to include `--read-only`. + +--- + ## Project structure ``` diff --git a/frontend/src/app/pages/Tools/Tools.tsx b/frontend/src/app/pages/Tools/Tools.tsx index 73aeef3a..049e47b3 100644 --- a/frontend/src/app/pages/Tools/Tools.tsx +++ b/frontend/src/app/pages/Tools/Tools.tsx @@ -309,6 +309,30 @@ const INTEGRATIONS: Integration[] = [ ), authType: 'oauth2', }, + { + id: 'github', + name: 'GitHub', + description: + 'GitHub repos, issues, PRs, code, workflows, gists, security, projects. 79 tools from the official github/github-mcp-server. Run scripts/setup-github-mcp.sh once to install the binary, then paste a Personal Access Token.', + mcp_config: { + type: 'stdio', + command: 'bash', + args: ['-c', 'exec "$HOME/.openswarm/bin/github-mcp-server" stdio --toolsets=all'], + }, + color: '#181717', + website: 'https://github.com/github/github-mcp-server', + connectLabel: 'Connect GitHub', + connectInstructions: 'Create a Personal Access Token at https://github.com/settings/tokens (fine-grained recommended) with the repo, read:org, and workflow scopes you want the agent to use. Then paste it below. First time only: run `bash scripts/setup-github-mcp.sh` in a terminal to download the github-mcp-server binary to ~/.openswarm/bin/.', + credentialFields: [ + { key: 'GITHUB_PERSONAL_ACCESS_TOKEN', label: 'GitHub Personal Access Token', placeholder: 'ghp_... or github_pat_...', type: 'password' }, + ], + icon: ( + + + + + ), + }, { id: 'linkedin', name: 'LinkedIn', @@ -638,7 +662,7 @@ const Tools: React.FC = () => { // browse the long tail. const CURATED_MCP_NAMES = useMemo(() => new Set([ 'google-workspace', 'microsoft-365', 'slack', 'discord', - 'notion', 'airtable', 'hubspot', 'reddit', 'youtube', 'instagram', 'linkedin', + 'notion', 'airtable', 'hubspot', 'reddit', 'youtube', 'instagram', 'linkedin', 'github', ]), []); const regServers = useMemo(() => { if (regSource !== 'curated') return regServersRaw; diff --git a/scripts/setup-github-mcp.sh b/scripts/setup-github-mcp.sh new file mode 100755 index 00000000..f5409b9b --- /dev/null +++ b/scripts/setup-github-mcp.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# One-time setup for the GitHub MCP server (github/github-mcp-server). +# Downloads the latest pre-built single binary for the current platform from +# the project's GitHub Releases and installs it at ~/.openswarm/bin/. +# OpenSwarm's GitHub tool tile spawns that binary directly (stdio transport). +# Re-running this is safe and is how you upgrade to a newer release. + +set -euo pipefail + +DEST_DIR="$HOME/.openswarm/bin" +DEST="$DEST_DIR/github-mcp-server" + +TAG="$(curl -fsSL https://api.github.com/repos/github/github-mcp-server/releases/latest \ + | python3 -c "import json,sys; print(json.load(sys.stdin)['tag_name'])")" + +OS="$(uname -s)" +ARCH="$(uname -m)" +case "$OS-$ARCH" in + Darwin-arm64) ASSET="github-mcp-server_Darwin_arm64.tar.gz" ;; + Darwin-x86_64) ASSET="github-mcp-server_Darwin_x86_64.tar.gz" ;; + Linux-x86_64) ASSET="github-mcp-server_Linux_x86_64.tar.gz" ;; + Linux-aarch64|Linux-arm64) ASSET="github-mcp-server_Linux_arm64.tar.gz" ;; + *) echo "error: unsupported platform $OS-$ARCH" >&2; exit 1 ;; +esac + +URL="https://github.com/github/github-mcp-server/releases/download/$TAG/$ASSET" +TMP="$(mktemp -d)" +trap 'rm -rf "$TMP"' EXIT + +echo "Downloading github-mcp-server $TAG ($OS-$ARCH)..." +curl -fSL "$URL" -o "$TMP/$ASSET" +tar -xzf "$TMP/$ASSET" -C "$TMP" + +mkdir -p "$DEST_DIR" +mv -f "$TMP/github-mcp-server" "$DEST" +chmod +x "$DEST" + +echo "Installed: $DEST" +"$DEST" --version 2>/dev/null || true