Jira Thing

- GitHub OAuth Integration: Securely authenticates users via GitHub, acting as an OAuth client to GitHub and an OAuth server to the MCP client.
- Dynamic Tool Loading: Demonstrates how to conditionally expose tools based on the authenticated user's identity.
- Example Tools: Includes two sample tools:

- A publicaddtool available to all authenticated users.
- A restrictedgenerateImagetool that is only available to a predefined list of authorized users.

git clone https://github.com/PortNumber53/mcp-jira-thing.git cd mcp-jira-thing

A React + Vite single-page application lives underfrontend/. It provides the GitHub sign-in flow for users and can be developed with the standard Vite server.

cd mcp-jira-thing npm install # install Worker + shared dependencies (repo root) cd frontend npm install # install local dependencies before development npm run dev # starts the Vite development server with HMR npm run dev:worker # runs the merged Worker locally on :18112

npm run build # runs tsc + vite build (Worker deploy is from repo root) npm run deploy # uploads the merged Worker and SPA assets via wrangler deploy

The Cloudflare Worker is defined at the repository root (src/index.ts). It serves the SPA fromfrontend/dist/clientat/and exposes the MCP server under/sse(and/mcp). Deployment is performed from the repo root withnpm run deploy, which builds the SPA first. Runningnpm run dev:workerinfrontend/starts the same merged Worker locally using../wrangler.jsonc.

Slack App (per-channel Jira project integration)

If you want Slack users to interact with Jirain the context of a Slack channel(e.g. create/search issues against a default Jira project per channel), connect a Slack app to this Worker and store a mapping:

- Slack channel ID→Jira project key(e.g.C01234567→ENG)

This repository doesnotship Slack endpoints yet, but the steps below describe the configuration you’ll need once you add them.

In Slack, create an app from scratch and enable:

- Interactivity & Shortcuts(optional but recommended)
- Slash Commands(recommended)
- Event Subscriptions(optional; useful for@yourappmentions)
- OAuth & Permissions

Add a redirect URL for the Worker, for example:

- http://localhost:18112/slack/oauth/callback(local)
- https://<your-worker>.<your-subdomain>.workers.dev/slack/oauth/callback(prod)

Suggested bot token scopes (adjust to your needs):

- commands: enable slash commands like/jira
- chat:write: post responses/messages
- channels:readand/orgroups:read: read channel metadata (public vs private)
- app_mentions:read(if using events for mentions)
- users:read(if you want to display usernames / enrich messages)

3) Configure Slack request URLs (Worker endpoints you’ll add)

Once implemented, Slack should point to Worker endpoints like:

- Slash command request URL:.../slack/commands
- Interactivity request URL:.../slack/interactions
- Events request URL(if enabled):.../slack/events

- Verify Slack signaturesusingSLACK_SIGNING_SECRET
- Ack within 3 seconds(useresponse_urlor async follow-ups for slow Jira calls)

4) Store “channel → Jira project” mapping

- Store mapping in Cloudflare KV(simple) or aDurable Object(strong consistency)
- Key by channel ID, value includes at least{ projectKey, updatedAt, updatedBy }

- slack:channel-project:C01234567→{"projectKey":"ENG","updatedAt":...}

One practical pattern is a/jiracommand that sets or uses the channel’s default project:

- Set default:/jira project set ENG
- Show default:/jira project get
- Create issue:/jira create "Bug title" --type Task
- Search:/jira search status=Open assignee=me

Implementation detail: the handler reads the channel ID from Slack payload, looks up the project key for that channel, then calls the existing Jira client/tooling insrc/tools/jira/to perform the requested action.

Add these as Wrangler secrets/vars (names are suggestions; pick a convention and stick to it):

- SLACK_SIGNING_SECRET: required to verify Slack requests
- SLACK_CLIENT_ID/SLACK_CLIENT_SECRET: required for Slack OAuth install flow
- SLACK_BOT_TOKEN: required to call Slack APIs (or store per-workspace tokens after OAuth)

If you support multiple Slack workspaces, store the workspace/team install info keyed byteam_id, not globally.

The Go backend exposes REST endpoints that serve data to the frontend (or other consumers). The initial implementation ships with:

- GET /healthz— simple health probe for load balancers and Jenkins smoke checks.
- GET /api/users?limit=50— returns a paginated list of NextAuth users from the database.

Create a copy ofbackend/env.exampleand provide the required values:

go testand the runtime code expect the environment variables to be present. When running locally you can export them or use a dotenv loader (direnv,dotenvx, etc.).

cd backend cp env.example .env # edit with your credentials (or export env vars) go test ./... go run ./cmd/server # or via make make test make run

# install once (requires Go 1.25+) go install github.com/air-verse/air@latest # start the watcher from the backend directory cd backend make dev # runs air -c .air.toml`

Air uses the configuration atbackend/.air.tomlto rebuild./tmp/mainwhenever Go or environment files change, then restarts the server transparently. Ensure your.envvalues are present before launching the watcher.

- Build/Test:make buildcompiles a Linux static binary atbackend/bin/mcp-backend.make testruns the unit tests. Both commands are orchestrated by the Jenkins pipeline (see below).
- Artifact:Jenkins compresses the binary tobackend/bin/mcp-backend.tar.gzand publishes it as a build artifact.
- Deploy script:scripts/deploy-backend.shcross-compiles the Linux binary, uploads it viascp, unpacks it under$DEPLOY_PATH, and optionally restarts a systemd service whenSERVICE_NAMEis provided.

This repository now contains a top-levelJenkinsfilethat performs the following stages:
- Checkout— pulls the repository for the current build.
- Go Test— runsgo test ./...insidebackend/.
- Build Backend— executesmake buildto generate themcp-backendbinary.
- Archive Artifact— tars the binary and archives it for later retrieval.
- Deploy (master only)— executesscripts/deploy-backend.sh, which expects the following environment variables to be supplied by Jenkins credentials or job configuration:

- DEPLOY_HOST: Production server host/IP (Arch Linux).
- DEPLOY_USER: SSH user with permission to write intoDEPLOY_PATHandrunsudo systemctl restarton the target service.
- DEPLOY_PATH: Target directory on the server (e.g./opt/mcp-backend).
- SERVICE_NAME(optional): systemd unit name to restart after deployment.

The deploy stage only runs for builds on themasterbranch, so feature branches remain test-only. Jenkins must provide SSH access, typically via an SSH key credential associated with theDEPLOY_USERaccount. Reviewscripts/deploy-backend.shfor additional details or customization points.

- Homepage URL:https://<your-worker-name>.<your-subdomain>.workers.dev
- Authorization callback URL:https://<your-worker-name>.<your-subdomain>.workers.dev/callback/github

For theSESSION_SECRET, you can generate a secure random string withopenssl rand -hex 32.

To grant access to restricted tools likegenerateImage, you must add the GitHub usernames of authorized users to theALLOWED_USERNAMESset insrc/index.ts.

Enter your worker's SSE URL (https://<your-worker-name>.<your-subdomain>.workers.dev/sse) and clickConnect. You will be redirected to GitHub to authenticate. Once authenticated, you will see the available tools in the Inspector.

- src/index.ts: The main entry point for the Cloudflare Worker. Defines the MCP server, its tools, and the logic for conditional tool access.
- src/github-handler.ts: Contains the logic for handling the GitHub OAuth flow.
- src/workers-oauth-utils.ts: Provides utility functions for the OAuth process, adapted from theworkers-oauth-providerlibrary.
- wrangler.jsonc: The configuration file for the Cloudflare Worker.
- package.json: Defines project scripts and dependencies.

The "generateImage" tool is restricted to specific GitHub users listed in theALLOWED_USERNAMESconfiguration: