github-brain 0.0.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tomáš Veselý
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -0,0 +1,200 @@
+<div align="center">
+  <img src="logo.svg" alt="GitHub Brain Logo" width="150" height="150">
+  <h1>GitHub Brain MCP Server</h1>
+</div>
+
+**GitHub Brain** is an experimental MCP server for summarizing GitHub discussions, issues, and pull requests. It helps answer questions like:
+
+- _What are the contributions of user X in the last month?_
+- _Summarize this month's discussions._
+
+https://github.com/user-attachments/assets/80910025-9d58-4367-af00-bf4c51e6ce86
+
+GitHub Brain complements (but does not replace) the [official GitHub MCP server](https://github.com/github/github-mcp-server). It uses a local database to store data pulled from GitHub, enabling:
+
+- Fast responses
+- More results than the standard 100-item API limit
+- Markdown output for token efficiency
+
+![](./docs/pull.png)
+
+As a bonus, GitHub Brain also includes a simple web-based UI for ultra-fast search of discussions, issues, and pull requests.
+
+![](./docs/ui.png)
+
+As a bonus, GitHub Brain also includes a Raycast extension for ultra-fast search of discussions, issues, and pull requests.
+
+![](./docs/raycast.png)
+
+GitHub Brain is [programmed in Markdown](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-using-markdown-as-a-programming-language-when-building-with-ai/).
+
+## Prerequisites
+
+- [Go](https://go.dev/doc/install) installed
+
+## Usage
+
+```sh
+scripts/run <command> [<args>]
+```
+
+**Workflow:**
+
+1. Populate the local database with the `pull` command.
+2. Start the MCP server with the `mcp` command.
+
+Re-run `pull` anytime to update the database with new GitHub data. You can do this while `mcp` is running, but MCP requests may temporarily return errors during the update.
+
+Each command has its own arguments. Some can be set via environment variables. The app will also load environment variables from a `.env` file in the GitHub Brain's home directory - `~/.github-brain` by default.
+You can change the home directory with the `-m` argument available for all commands. When executing `scripts/run`, the home directory is set to the checkout directory.
+
+<details>
+    <summary>Example .env file</summary>
+
+    GITHUB_TOKEN=your_github_token
+    ORGANIZATION=my-org
+
+</details>
+
+### `pull`
+
+Populate the local database with GitHub data.
+
+Example:
+
+```sh
+scripts/run pull -o my-org
+```
+
+The first call for an organization may take a while. Subsequent calls are faster, updating only with new data.
+
+| Argument | Variable                | Description                                                                                                                                                                   |
+| :------- | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-t`     | `GITHUB_TOKEN`          | Your GitHub [personal token](https://github.com/settings/personal-access-tokens) to access the API. **Required.**                                                             |
+| `-o`     | `ORGANIZATION`          | The GitHub organization to pull data from. **Required.**                                                                                                                      |
+| `-m`     |                         | GitHub Brain home directory. Default: `~/.github-brain` or the repo checkout directory if executed via `scripts/run`.                                                         |
+| `-i`     |                         | Only pull selected entities. Choose from: `repositories`, `discussions`, `issues`, `pull-requests`. Comma-separated list.                                                     |
+| `-f`     |                         | Remove all data before pulling. If combined with `-i`, only the specified items will be removed.                                                                              |
+| `-e`     | `EXCLUDED_REPOSITORIES` | Comma-separated list of repositories to exclude from the pull of discussions, issues, and pull requests. Useful for large repositories that are not relevant to the analysis. |
+
+<details>
+    <summary>Personal access token scopes</summary>
+
+    Use the [fine-grained personal access tokens](https://github.com/settings/personal-access-tokens).
+
+    For private organizations, the token must have the following configuration:
+
+    - Repository permissions: Read access to discussions, issues, metadata, and pull requests. Click [here](https://github.com/settings/personal-access-tokens/new?name=github-brain&description=http%3A%2F%2Fgithub.com%2Fwham%2Fgithub-brain&issues=read&pull_requests=read&discussions=read) to generate.
+
+    For public organizations, an empty token is sufficient, as the data is publicly accessible.
+
+</details>
+
+### `mcp`
+
+Start the MCP server using the local database.
+
+Example:
+
+```sh
+scripts/run mcp -o my-org
+```
+
+| Argument | Variable       | Description                                                                                                           |
+| :------- | :------------- | :-------------------------------------------------------------------------------------------------------------------- |
+| `-o`     | `ORGANIZATION` | The GitHub organization to work with. **Required.**                                                                   |
+| `-m`     |                | GitHub Brain home directory. Default: `~/.github-brain` or the repo checkout directory if executed via `scripts/run`. |
+
+### `ui`
+
+Start the UI server, which provides a web-based interface for interacting with the GitHub data. Alternative to MCP for quick lookups.
+
+Example:
+
+```sh
+scripts/run ui -o my-org
+```
+
+| Argument | Variable       | Description                                                                                                           |
+| :------- | :------------- | :-------------------------------------------------------------------------------------------------------------------- |
+| `-o`     | `ORGANIZATION` | The GitHub organization to work with. **Required.**                                                                   |
+| `-m`     |                | GitHub Brain home directory. Default: `~/.github-brain` or the repo checkout directory if executed via `scripts/run`. |
+| `-p`     | `UI_PORT`      | Port for the UI server. Default: `8080`.                                                                              |
+
+### Additional Arguments
+
+**Version:**
+
+```sh
+github-brain --version
+```
+
+Displays the current version (commit hash and build date).
+
+## Installation
+
+### NPM (Recommended)
+
+Install globally:
+
+```sh
+npm install -g github-brain
+```
+
+Then run commands directly:
+
+```sh
+github-brain pull -o my-org
+github-brain mcp -o my-org
+github-brain ui -o my-org
+```
+
+### From Source
+
+`scripts/run` is a convenience script that runs the MCP server. It builds the Go code and runs the `mcp` command with the checkout directory as the working directory. As a result, the SQLite database will be created in the `db` folder of the checkout directory.
+
+### Claude
+
+Add to the Claude MCP configuration file:
+
+```json
+{
+  "mcpServers": {
+    "github-brain": {
+      "type": "stdio",
+      "command": "<path-to-the-checkout-directory>/scripts/run",
+      "args": ["mcp"]
+    }
+}
+```
+
+Where `<path-to-the-checkout-directory>` is the path to the GitHub Brain repository on your local machine. Merge if `mcpServers` already exists.
+
+### VS Code
+
+Add to the VS Code MCP configuration file:
+
+```json
+{
+  "servers": {
+    "github-brain": {
+      "type": "stdio",
+      "command": "<path-to-the-checkout-directory>/scripts/run",
+      "args": ["mcp"],
+      "version": "0.0.1"
+    }
+  }
+}
+```
+
+Where `<path-to-the-checkout-directory>` is the path to the GitHub Brain repository on your local machine. Merge if `servers` already exists.
+
+## Raycast Extension
+
+Run the Raycast extension with:
+
+```sh
+scripts/raycast
+```
+
+The extension uses the MCP server to search GitHub data.

package/bin/github-brain.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+// Platform-specific package mapping
+// Note: Windows package uses simplified name "github-brain-windows" instead of
+// "github-brain-win32-x64" to avoid NPM's spam detection which flags packages
+// with platform-specific suffixes like win32-x64.
+const PLATFORMS = {
+  "darwin-arm64": "github-brain-darwin-arm64",
+  "darwin-x64": "github-brain-darwin-x64",
+  "linux-arm64": "github-brain-linux-arm64",
+  "linux-x64": "github-brain-linux-x64",
+  "win32-x64": "github-brain-windows",
+};
+
+function getPlatformPackage() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  // Map Node.js arch to our naming convention
+  const archMap = {
+    arm64: "arm64",
+    x64: "x64",
+  };
+
+  const mappedArch = archMap[arch];
+  if (!mappedArch) {
+    throw new Error(`Unsupported architecture: ${arch}`);
+  }
+
+  const key = `${platform}-${mappedArch}`;
+  const pkg = PLATFORMS[key];
+
+  if (!pkg) {
+    throw new Error(`Unsupported platform: ${platform} ${arch}`);
+  }
+
+  return pkg;
+}
+
+function getBinaryPath() {
+  try {
+    const pkg = getPlatformPackage();
+    const binaryName =
+      process.platform === "win32" ? "github-brain.exe" : "github-brain";
+
+    // Try to resolve the binary from the platform-specific package
+    const pkgPath = require.resolve(`${pkg}/package.json`);
+    const pkgDir = path.dirname(pkgPath);
+    const binaryPath = path.join(pkgDir, binaryName);
+
+    if (fs.existsSync(binaryPath)) {
+      return binaryPath;
+    }
+
+    throw new Error(`Binary not found at ${binaryPath}`);
+  } catch (error) {
+    console.error("Error:", error.message);
+    console.error(
+      "\nThe platform-specific binary package may not be installed."
+    );
+    console.error("Try running: npm install");
+    process.exit(1);
+  }
+}
+
+// Get the binary path and execute it
+const binaryPath = getBinaryPath();
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  windowsHide: false,
+});
+
+process.exit(result.status || 0);

package/install.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+// This install script runs after npm install and verifies the binary is accessible
+const { execSync } = require("child_process");
+const path = require("path");
+
+try {
+  // Try to run the binary with --version to verify it works
+  const binPath = path.join(__dirname, "bin", "github-brain.js");
+  execSync(`node "${binPath}" --version`, { stdio: "inherit" });
+  console.log("✓ github-brain installed successfully!");
+} catch (error) {
+  // If the binary isn't available yet (e.g., during CI or --no-optional),
+  // that's okay - it will be resolved when the user tries to run it
+  console.log("✓ github-brain package installed");
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "github-brain",
+  "version": "0.0.9",
+  "description": "MCP server for searching GitHub discussions, issues, and pull requests",
+  "bin": {
+    "github-brain": "bin/github-brain.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wham/github-brain.git"
+  },
+  "keywords": [
+    "github",
+    "mcp",
+    "search",
+    "discussions",
+    "issues",
+    "pull-requests"
+  ],
+  "author": "wham",
+  "license": "MIT",
+  "optionalDependencies": {
+    "github-brain-darwin-arm64": "0.0.9",
+    "github-brain-darwin-x64": "0.0.9",
+    "github-brain-linux-arm64": "0.0.9",
+    "github-brain-linux-x64": "0.0.9",
+    "github-brain-windows": "0.0.9"
+  },
+  "files": [
+    "bin",
+    "install.js"
+  ]
+}