github-brain 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +45 -41
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -3,50 +3,56 @@
3
3
  <h1>GitHub Brain MCP Server</h1>
4
4
  </div>
5
5
 
6
- **GitHub Brain** is an experimental MCP server for summarizing GitHub discussions, issues, and pull requests. It helps answer questions like:
6
+ **GitHub Brain** is an experimental MCP server for summarizing GitHub discussions, issues, and pull requests. Answer questions like:
7
7
 
8
8
  - _What are the contributions of user X in the last month?_
9
9
  - _Summarize this month's discussions._
10
10
 
11
11
  https://github.com/user-attachments/assets/80910025-9d58-4367-af00-bf4c51e6ce86
12
12
 
13
- 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:
13
+ GitHub Brain complements (but does not replace) the [official GitHub MCP server](https://github.com/github/github-mcp-server). It stores GitHub data in a local database for:
14
14
 
15
15
  - Fast responses
16
- - More results than the standard 100-item API limit
17
- - Markdown output for token efficiency
16
+ - More than the standard 100-item API limit
17
+ - Token-efficient Markdown output
18
18
 
19
19
  ![](./docs/pull.png)
20
20
 
21
- As a bonus, GitHub Brain also includes a simple web-based UI for ultra-fast search of discussions, issues, and pull requests.
21
+ GitHub Brain also includes a web-based UI for ultra-fast search:
22
22
 
23
23
  ![](./docs/ui.png)
24
24
 
25
- As a bonus, GitHub Brain also includes a Raycast extension for ultra-fast search of discussions, issues, and pull requests.
25
+ And a Raycast extension:
26
+
27
+
26
28
 
27
29
  ![](./docs/raycast.png)
28
30
 
29
31
  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/).
30
32
 
31
- ## Prerequisites
33
+ ## Installation
32
34
 
33
- - [Go](https://go.dev/doc/install) installed
35
+ ```sh
36
+ npm i -g github-brain
37
+ ```
38
+
39
+ Or use `npx github-brain` to run without installing globally.
34
40
 
35
41
  ## Usage
36
42
 
37
43
  ```sh
38
- scripts/run <command> [<args>]
44
+ github-brain <command> [<args>]
39
45
  ```
40
46
 
41
47
  **Workflow:**
42
48
 
43
- 1. Populate the local database with the `pull` command.
44
- 2. Start the MCP server with the `mcp` command.
49
+ 1. Use `pull` to populate the local database
50
+ 2. Use `mcp` to start the MCP server
45
51
 
46
- 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.
52
+ Re-run `pull` anytime to update the database with new GitHub data.
47
53
 
48
54
  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.
49
- 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.
55
+ You can change the home directory with the `-m` argument available for all commands.
50
56
 
51
57
  <details>
52
58
  <summary>Example .env file</summary>
@@ -63,30 +69,28 @@ Populate the local database with GitHub data.
63
69
  Example:
64
70
 
65
71
  ```sh
66
- scripts/run pull -o my-org
72
+ github-brain pull -o my-org
67
73
  ```
68
74
 
69
- The first call for an organization may take a while. Subsequent calls are faster, updating only with new data.
75
+ The first run may take a while. Subsequent runs are faster, fetching only new data.
70
76
 
71
77
  | Argument | Variable | Description |
72
78
  | :------- | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
73
79
  | `-t` | `GITHUB_TOKEN` | Your GitHub [personal token](https://github.com/settings/personal-access-tokens) to access the API. **Required.** |
74
80
  | `-o` | `ORGANIZATION` | The GitHub organization to pull data from. **Required.** |
75
- | `-m` | | GitHub Brain home directory. Default: `~/.github-brain` or the repo checkout directory if executed via `scripts/run`. |
76
- | `-i` | | Only pull selected entities. Choose from: `repositories`, `discussions`, `issues`, `pull-requests`. Comma-separated list. |
77
- | `-f` | | Remove all data before pulling. If combined with `-i`, only the specified items will be removed. |
78
- | `-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. |
81
+ | `-m` | | Home directory. Default: `~/.github-brain` (or checkout directory if run via `scripts/run`). |
82
+ | `-i` | | Pull only selected entities: `repositories`, `discussions`, `issues`, `pull-requests` (comma-separated). |
83
+ | `-f` | | Remove all data before pulling. With `-i`, removes only specified items. |
84
+ | `-e` | `EXCLUDED_REPOSITORIES` | Repositories to exclude (comma-separated). Useful for large repos not relevant to your analysis. |
79
85
 
80
86
  <details>
81
87
  <summary>Personal access token scopes</summary>
82
88
 
83
- Use the [fine-grained personal access tokens](https://github.com/settings/personal-access-tokens).
84
-
85
- For private organizations, the token must have the following configuration:
89
+ Use [fine-grained personal access tokens](https://github.com/settings/personal-access-tokens).
86
90
 
87
- - 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.
91
+ **Private organizations:** Token needs read access to discussions, issues, metadata, and pull requests. [Generate token](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).
88
92
 
89
- For public organizations, an empty token is sufficient, as the data is publicly accessible.
93
+ **Public organizations:** Any token works (data is publicly accessible).
90
94
 
91
95
  </details>
92
96
 
@@ -97,29 +101,27 @@ Start the MCP server using the local database.
97
101
  Example:
98
102
 
99
103
  ```sh
100
- scripts/run mcp -o my-org
104
+ github-brain mcp -o my-org
101
105
  ```
102
106
 
103
107
  | Argument | Variable | Description |
104
108
  | :------- | :------------- | :-------------------------------------------------------------------------------------------------------------------- |
105
- | `-o` | `ORGANIZATION` | The GitHub organization to work with. **Required.** |
106
- | `-m` | | GitHub Brain home directory. Default: `~/.github-brain` or the repo checkout directory if executed via `scripts/run`. |
109
+ | `-o` | `ORGANIZATION` | GitHub organization. **Required.** |
110
+ | `-m` | | Home directory. Default: `~/.github-brain` (or checkout directory if run via `scripts/run`). |
107
111
 
108
112
  ### `ui`
109
113
 
110
- Start the UI server, which provides a web-based interface for interacting with the GitHub data. Alternative to MCP for quick lookups.
111
-
112
- Example:
114
+ Start the web UI for quick searches (alternative to MCP).
113
115
 
114
116
  ```sh
115
- scripts/run ui -o my-org
117
+ github-brain ui -o my-org
116
118
  ```
117
119
 
118
120
  | Argument | Variable | Description |
119
121
  | :------- | :------------- | :-------------------------------------------------------------------------------------------------------------------- |
120
- | `-o` | `ORGANIZATION` | The GitHub organization to work with. **Required.** |
121
- | `-m` | | GitHub Brain home directory. Default: `~/.github-brain` or the repo checkout directory if executed via `scripts/run`. |
122
- | `-p` | `UI_PORT` | Port for the UI server. Default: `8080`. |
122
+ | `-o` | `ORGANIZATION` | GitHub organization. **Required.** |
123
+ | `-m` | | Home directory. Default: `~/.github-brain` (or checkout directory if run via `scripts/run`). |
124
+ | `-p` | `UI_PORT` | Port. Default: `8080`. |
123
125
 
124
126
  ### Additional Arguments
125
127
 
@@ -131,9 +133,7 @@ github-brain --version
131
133
 
132
134
  Displays the current version (commit hash and build date).
133
135
 
134
- ## Installation
135
-
136
- `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.
136
+ ## MCP Configuration
137
137
 
138
138
  ### Claude
139
139
 
@@ -144,13 +144,13 @@ Add to the Claude MCP configuration file:
144
144
  "mcpServers": {
145
145
  "github-brain": {
146
146
  "type": "stdio",
147
- "command": "<path-to-the-checkout-directory>/scripts/run",
147
+ "command": "github-brain",
148
148
  "args": ["mcp"]
149
149
  }
150
150
  }
151
151
  ```
152
152
 
153
- Where `<path-to-the-checkout-directory>` is the path to the GitHub Brain repository on your local machine. Merge if `mcpServers` already exists.
153
+ Merge with existing `mcpServers` if present.
154
154
 
155
155
  ### VS Code
156
156
 
@@ -161,7 +161,7 @@ Add to the VS Code MCP configuration file:
161
161
  "servers": {
162
162
  "github-brain": {
163
163
  "type": "stdio",
164
- "command": "<path-to-the-checkout-directory>/scripts/run",
164
+ "command": "github-brain",
165
165
  "args": ["mcp"],
166
166
  "version": "0.0.1"
167
167
  }
@@ -169,7 +169,7 @@ Add to the VS Code MCP configuration file:
169
169
  }
170
170
  ```
171
171
 
172
- Where `<path-to-the-checkout-directory>` is the path to the GitHub Brain repository on your local machine. Merge if `servers` already exists.
172
+ Merge with existing `servers` if present.
173
173
 
174
174
  ## Raycast Extension
175
175
 
@@ -180,3 +180,7 @@ scripts/raycast
180
180
  ```
181
181
 
182
182
  The extension uses the MCP server to search GitHub data.
183
+
184
+ ## Development
185
+
186
+ `scripts/run` builds and runs `github-brain` with the checkout directory as home (database in `db/`, config in `.env`).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "github-brain",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
4
4
  "description": "MCP server for searching GitHub discussions, issues, and pull requests",
5
5
  "bin": {
6
6
  "github-brain": "bin/github-brain.js"
@@ -23,11 +23,11 @@
23
23
  "author": "wham",
24
24
  "license": "MIT",
25
25
  "optionalDependencies": {
26
- "github-brain-darwin-arm64": "1.0.0",
27
- "github-brain-darwin-x64": "1.0.0",
28
- "github-brain-linux-arm64": "1.0.0",
29
- "github-brain-linux-x64": "1.0.0",
30
- "github-brain-windows": "1.0.0"
26
+ "github-brain-darwin-arm64": "1.0.2",
27
+ "github-brain-darwin-x64": "1.0.2",
28
+ "github-brain-linux-arm64": "1.0.2",
29
+ "github-brain-linux-x64": "1.0.2",
30
+ "github-brain-windows": "1.0.2"
31
31
  },
32
32
  "files": [
33
33
  "bin",