Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
8d521ec
Enforce GitBucket repository permissions on every MCP tool
claude Oct 23, 2026
99728cf
oauth: discovery metadata, PKCE and scopes
claude Oct 23, 2026
c79876f
oauth: delegate protocol types to the SDK GitBucket already ships
claude Oct 23, 2026
1cd49dc
oauth: grant, code, refresh and token storage
claude Oct 23, 2026
9a00734
oauth: the HTTP path, bearer authentication and scope enforcement
claude Oct 23, 2026
f46de69
oauth: let an operator open client metadata fetching to loopback
claude Oct 23, 2026
af50457
oauth: make the rotation concurrency controls independent of scheduling
claude Oct 23, 2026
1b978d8
Make the OAuth migration actually run
claude Oct 23, 2026
83e785b
oauth: a refresh binding failure must not revoke the grant
claude Oct 23, 2026
aaeba59
docs: describe what is implemented, and what has not been tried
claude Oct 23, 2026
13e1db2
Add the live-instance integration gates
claude Oct 23, 2026
6bee0af
oauth: offline controls for the scope gate
claude Oct 24, 2026
dd3eb4f
itest: check the reported version against the artifact under test
claude Oct 24, 2026
7648022
itest: an installation, upgrade and restart gate
claude Oct 24, 2026
712a9c7
docs: record what the gates have now actually run
claude Oct 24, 2026
7282304
oauth: send the client metadata request to the address that was checked
claude Oct 24, 2026
7de2e08
oauth: a spent or dead credential is not evidence of theft
claude Oct 24, 2026
27d123c
oauth: check the audience where the credential is used
claude Oct 24, 2026
3132563
docs: describe the corrected behaviour, and add the HTTP controls for it
claude Oct 24, 2026
64e8ec5
oauth: a truncated HTTP message is not a client registration
claude Oct 24, 2026
d022479
itest: a server failure is not an authorization refusal
claude Oct 24, 2026
d2df637
oauth: restore the transport bounds the maintained stack does not apply
claude Oct 24, 2026
bafbe08
itest: each refresh scenario requires the refusal it is entitled to
claude Oct 24, 2026
b33a24b
repos: the listing's counters were placeholders, not measurements
claude Oct 24, 2026
acd5ee8
repos: authorize the record that is published, not the one enumerated
claude Oct 24, 2026
be42460
test: name the role-removal control for what it establishes
claude Oct 24, 2026
6b25821
docs: describe what exists, not what was once true
claude Oct 24, 2026
6084f14
docs: the integration command never ran as written
claude Oct 24, 2026
4251948
docs: a declared version is not an artifact identity
claude Oct 24, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,5 @@ target/
*.war
*.ear
!gradle-wrapper.jar
__pycache__/
*.pyc
78 changes: 60 additions & 18 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,46 +16,88 @@ You'll need **Java 17+** and **Gradle** (the wrapper is included).

```
src/
main/resources/
gitbucket-plugin.properties # the descriptor GitBucket reads
update/mcp-plugin_1.0.xml # Liquibase changelog for the OAuth tables
main/scala/
Plugin.scala # GitBucket plugin entry point
Plugin.scala # GitBucket entry point; declares `versions`
com/newsrx/mcpplugin/
MCPController.scala # HTTP routes, auth, JSON-RPC dispatch
MCPPlugin.scala # registration, routes, anonymous paths
MCPController.scala # HTTP, authentication, JSON-RPC dispatch
PluginDescriptor.scala # reads the packaged descriptor, not a literal
mcp/
JsonRpc.scala # JSON-RPC 2.0 parsing/formatting
ToolDef.scala # Tool interface + registry + schema helpers
JsonRpc.scala # JSON-RPC 2.0 parsing and formatting
ToolDef.scala # tool interface, registry, schema helpers
StrictArgs.scala # argument parsing that refuses coercion
Timestamps.scala # UTC ISO-8601 formatting
oauth/ # the authorization server
OAuthConfig.scala # configuration, and the rules it enforces
OAuthEndpoints.scala # authorize, token, revoke
OAuthStore.scala # grants, codes, rotation, replay detection
Metadata.scala ConsentView.scala # discovery documents, consent screen
ClientMetadata.scala # client ID metadata documents, SSRF policy
PinnedConnection.scala # the fetcher: destination pinning and bounds
Pkce.scala Secrets.scala Scopes.scala ChallengeError.scala
AuthenticatedCaller.scala # the caller, and the scope it holds
tools/
IssueTools.scala # 6 issue management tools
PullRequestTools.scala # 6 pull request tools
IdentityTools.scala # 1 identity tool
IssueTools.scala # 7 issue tools
PullRequestTools.scala # 9 pull request tools
RepositoryTools.scala # 2 repository tools
SessionSupport.scala # Database session acquisition
test/scala/com/newsrx/mcpplugin/
JsonRpcSpec.scala # JSON-RPC protocol tests (15)
ToolDefSpec.scala # Registry and schema tests (23)
ToolArgParseSpec.scala # Argument parsing tests (17)
Authz.scala # the repository read/write guards
SessionSupport.scala # database session acquisition
test/scala/ # the offline suites: `./gradlew test`
itest/ # live-instance gates; see itest/README.md
scripts/
integration_test.py # End-to-end integration test runner
integration_test.py # the original pre-OAuth runner, superseded
# by itest/integration.py
```

Per-file tool counts are there to orient you, not as an inventory to keep in
step; `ToolRegistrySpec` is what actually pins the registry.

## Running tests

```bash
./gradlew test # unit tests
python3 scripts/integration_test.py ... # integration tests (needs GitBucket)
./gradlew test # the offline suites
python3 itest/selftest.py # the gates' own guards; no server, no network
```

Everything else needs a **disposable** GitBucket with the plugin installed —
the gates create accounts and repositories and deliberately attempt refused
writes, so they must never be pointed at an instance holding anything real.
`itest/README.md` has the commands, the system properties each gate needs, and
what each one covers.

## Adding a new tool

1. Add a class in the appropriate `*Tools.scala` file, extending `ToolDef` and the relevant service trait.
2. Register it in `ToolDef.scala` → `ToolRegistry.all`.
3. Add unit tests in `ToolDefSpec.scala` and/or `ToolArgParseSpec.scala`.
4. Add an integration test case in `scripts/integration_test.py`.
1. Add a class in the appropriate `*Tools.scala` file, extending `ToolDef` and
the relevant service trait.
2. **Declare `requiredScope`.** It is an abstract member of `ToolDef`, so a
tool that omits it does not compile — which is deliberate: the alternative
is a tool that quietly defaults to the weaker requirement. `McpScope.Read`
for a tool that only reads, `McpScope.Write` for anything that changes
state. A `mcp:read` grant cannot call a `Write` tool, and the check happens
before the tool runs; the repository guard in `Authz` still applies inside
it, so the scope is a ceiling and never a substitute for permissions.
3. Register it in `ToolDef.scala` → `ToolRegistry.all`.
4. Add unit tests: schema and registry in `ToolDefSpec.scala` /
`ToolRegistrySpec.scala`, argument parsing in `ToolArgParseSpec.scala` or
`StrictArgsSpec.scala`, and the tool's behaviour through its real `execute`
in `tools/ToolExecutionSpec.scala`.
5. Add a case to `itest/integration.py`, which compares the tool's answer with
GitBucket's own REST API against each repository visibility and each
collaborator role.
6. Add its row to the tool table in `README.md`, including the scope.

## Pull requests

- Keep changes focused — one feature or fix per PR.
- All existing tests must pass (`./gradlew test`).
- Match the existing code style (no comments explaining *what*, only *why* when non-obvious).
- Update `README.md` if you add or change tool behaviour.
- Use neutral example identities in fixtures (`example-org`, `example.com`,
`example.invalid`). Never a real host, account or deployment address.

## Reporting issues

Expand Down
130 changes: 95 additions & 35 deletions DEPLOY.md
Original file line number Diff line number Diff line change
@@ -1,62 +1,122 @@
# Deploy to a GitBucket instance — verified runbook
# Installing on a GitBucket instance

Tested 2026-09-03 against a local GitBucket 4.44.0 instance (JDK 21, `~/Downloads/gitbucket.war`
run standalone with Jetty). Full round trip confirmed: build, hot-deploy, MCP handshake, read tool
call, write tool call.
Generic runbook. It names no particular instance: substitute your own host,
account and `GITBUCKET_HOME`. For what the plugin requires, which GitBucket
versions have been tested and what has not been tried, see
[README.md](README.md) and [docs/authentication.md](docs/authentication.md);
this page is only the mechanics of getting the JAR in place.

## 1. Build

```bash
./gradlew shadowJar
```

Produces `build/libs/gitbucket-mcp-plugin-<version>.jar`.

## 2. Deploy
Drop the jar into the target GitBucket's plugin directory:
## 2. Install

Copy the JAR into the target GitBucket's plugin directory:

```bash
cp build/libs/gitbucket-mcp-plugin-<version>.jar $GITBUCKET_HOME/plugins/
cp build/libs/gitbucket-mcp-plugin-<version>.jar "$GITBUCKET_HOME/plugins/"
```
GitBucket runs a `PluginWatchThread` that watches that directory and **hot-reloads on file create** —
no GitBucket restart needed. Confirmed in logs:

GitBucket runs a `PluginWatchThread` over that directory and reloads on file
creation, so a restart is not always required:

```
INFO g.core.plugin.PluginWatchThread - ENTRY_CREATE: gitbucket-mcp-plugin-<version>.jar
INFO g.core.plugin.PluginWatchThread - Reloading plugins...
INFO g.core.plugin.PluginRegistry - Initialize gitbucket-mcp-plugin-<version>.jar
INFO g.core.plugin.PluginWatchThread - Reloading finished.
```
Reload took under 100ms in testing.

Prefer a restart when **replacing** an installed version: the plugin's
database migration runs from the loaded `Plugin` class's declared versions,
and `itest/upgrade_gate.py` is what exercises install, replacement, migration
and restart as a sequence.

### Replacing: remove the old JAR, do not rename the new one

Leave two JARs declaring the same plugin id in that directory and GitBucket
loads **one** of them. Which one is not something to leave to chance, and
neither a restart nor a new filename settles it. From GitBucket's own scan:

- candidates are ordered by version **descending**, and that version is parsed
from the **file name**, not from the packaged descriptor;
- a file name the version pattern does not match counts as `0.0.0`, so
`gitbucket-mcp-plugin-0.1.0-new.jar` sorts *below* the
`gitbucket-mcp-plugin-0.1.0.jar` it was meant to supersede;
- the first candidate for a given plugin id wins and the rest are skipped,
logged as `Plugin <id> is duplicated. <jar> is available.`

So: **delete the previous JAR** rather than renaming around it, and read that
log line as the signal that one was left behind. Two builds of this plugin can
declare the same version — the version is not an identity — so equal
declared versions make the choice arbitrary rather than newest-wins.

`$GITBUCKET_HOME/plugins/.installed/` is GitBucket's own copy of what it
loaded. It is rebuilt on each scan, so it is a witness and never the place to
install into.

## 3. Verify

```bash
curl http://<host>/plugin-mcp/health
# {"status":"ok","protocol":"MCP","transport":"Streamable HTTP"}
```

MCP JSON-RPC handshake (Basic auth, GitBucket username + password or PAT):
Then the MCP handshake. HTTP Basic takes a GitBucket account's own
credentials and needs no configuration:

```bash
curl -u <user>:<pass> -H "Content-Type: application/json" \
curl -u <user>:<password> \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}' \
http://<host>/plugin-mcp/
```
Returned in testing:
```json
{"jsonrpc":"2.0","result":{"capabilities":{"tools":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"prompts":{"listChanged":false}},"serverInfo":{"name":"gitbucket-mcp-plugin","version":"0.1.0"},"protocolVersion":"2025-03-26"},"id":1}
```

`tools/list` returned all 14 documented tools (list/get/create/close/reopen for issues and PRs, plus
repo tools). Round-tripped both a read (`list_repositories`) and a write (`create_issue`) tool call
against a real test repo — both worked and reflected actual GitBucket state.

## 4. Known gaps / things to check on the target instance
- Auth tested here as HTTP Basic with the GitBucket account's own password (`root:root` on the test
instance). GitBucket's `/api/v3/user/access_tokens` endpoint returned 404 on 4.44.0 — if the prod
instance is on a different version, verify whether PAT creation via API works there, or just use
the account password / an existing PAT the same way `git` already authenticates against it.
- GitBucket version compatibility per this plugin's own README: 4.42.0–4.46.0, Java 17 or 21. The
4.44.0 test instance is inside that range.
- Not tested: TLS termination in front of GitBucket, concurrent multi-plugin interaction beyond the
bundled gist/emoji/notifications/pages plugins, or behavior under GitBucket's private-repo/LDAP auth
modes.
- This was validated against a disposable local instance, not the shared corporate GitBucket at
`192.168.214.202` — deploying there is a separate, deliberate infra change for whoever owns that
box.

`tools/list` then enumerates the tools, each with the scope it requires.

`serverInfo.version` in that reply comes from the descriptor packaged in the
installed JAR rather than from a literal in the source, which is worth having
— but it reports the **declared version only**, and that is not the artifact.
Two builds with different contents and different behaviour can declare the
same version, and this plugin's have: every build in this contribution
declares `0.1.0`.

**Artifact identity is the file hash.** Compare the hash of the JAR you placed
in the plugins directory with the hash of the build you chose:

```bash
sha256sum "$GITBUCKET_HOME/plugins/gitbucket-mcp-plugin-<version>.jar"
# must equal the hash recorded for the build you intended to install
```

Use the handshake, `serverInfo.version` and `/health` as **smoke checks** —
they tell you something is up and answering — and the hash for *what* is
running.

For the browser authorization flow, set the external base URL — OAuth stays
off until you do, and nothing else changes:

```
-Dgitbucket.mcp.oauth.baseUrl=https://<your-gitbucket>
```

[docs/authentication.md](docs/authentication.md) covers what that value
governs and why it is not taken from a request header.

## Before deploying anywhere shared

- Identify the exact artifact by hash, as above, after copying it onto the
target — not by its declared version and not by its file name.
- Run the gates against a **disposable** instance, never a shared one: they
create accounts and repositories and deliberately attempt refused writes.
See [itest/README.md](itest/README.md).
- Untested configurations are listed in [README.md](README.md) — among them
TLS termination by a reverse proxy, GitBucket's LDAP authentication, and
interaction with plugins beyond the bundled ones. Untested is not the same
as known-broken, but it is not evidence either.
Loading