bugboard-mcp

bugboard-mcp gives an MCP client access to projects, versions, bugs, history,
subscriptions, and votes in the 1C Bugboard. It uses the browser session you
already have; it does not collect credentials or automate the browser.

The server is unofficial and experimental. Use it with an account that is
allowed to access the target Bugboard data.

What it does

• Lists projects, versions, recent and subscribed bugs, and bugs you voted for.
• Searches by bug number or full-text query, then returns bug details and
  reference-redacted history.
• Creates session-local opaque handles so MCP clients never receive Bugboard
  references.
• Subscribes, unsubscribes, votes, and unvotes safely: every write checks the
  current state, skips a no-op, and confirms the result.

The default transport is Streamable HTTP at http://127.0.0.1:8000/mcp. For
local integrations and smoke checks, use stdio instead.

Run it

Install the pinned toolchain:

mise install

Set BUGBOARD_COOKIE directly, or create an env-file outside the repository:

BUGBOARD_COOKIE=...

Start the server with a direct value:

$env:BUGBOARD_COOKIE="..."
mise run run

Or point it to an env-file:

$env:BUGBOARD_SESSION_ENV="C:\path\outside\repo\bugboard.env"
mise run run

The server uses a direct BUGBOARD_COOKIE in preference to the env-file. It
loads only BUGBOARD_COOKIE from that file. It obtains the
deployment-specific X-G5-Version from the authenticated Bugboard shell and
keeps it in memory. Replace an expired cookie and restart the server. A read
may retry once after a Bugboard deployment change; a write never retries on its
own.

Use mise run run:stdio to use stdio. BUGBOARD_MCP_BIND can change the
address or port.

Tool inputs

List and search tools return opaque handles. Handles work only in the MCP
session that created them. bug_get* and bug_open_in_browser take either a
bug_handle or a bug_number; write tools require bug_handle, and vote
tools also require vote_kind. project_get_versions, project_subscribe,
and project_unsubscribe require project_handle. version_get_bugs needs a
project handle and the exact version title returned by project_get_versions.

bug_list_recent returns the first page. bug_search requires a query:
ASCII digits select an exact bug number, while other text runs a full-text
search. Limits range from 1 to 50. Pagination will be added only after its
request shape is verified.

Development

Run the complete local and CI check:

mise run verify

The workflow in .github/workflows/ci.yml runs the same command on Ubuntu and
Windows. The wire-level crate is documented in
crates/e1c-element-rpc/README.md.

Docker

The image runs Streamable HTTP by default on port 8000. Publish it only to the
host loopback interface, because the MCP endpoint has no separate client
authentication. Build it with:

mise run docker:build

Pushes to main publish ghcr.io/bapho-bush/bugboard-mcp:latest and an
immutable Git commit tag. While the repository is private, pull it with a
GitHub token that has read:packages:

docker pull ghcr.io/bapho-bush/bugboard-mcp:latest

Run HTTP MCP for Codex:

docker run --rm -d --name bugboard-mcp `
  -p 127.0.0.1:18080:8000 `
  -e "BUGBOARD_COOKIE=$env:BUGBOARD_COOKIE" `
  ghcr.io/bapho-bush/bugboard-mcp:latest

Configure Codex with url = "http://127.0.0.1:18080/mcp". Do not use
-p 18080:8000, which publishes the unauthenticated MCP endpoint beyond the
local machine.

Run stdio instead by overriding the transport:

docker run --rm -i `
  -e "BUGBOARD_MCP_TRANSPORT=stdio" `
  -e "BUGBOARD_COOKIE=$env:BUGBOARD_COOKIE" `
  ghcr.io/bapho-bush/bugboard-mcp:latest

An external session file remains supported for either transport when mounting
it is preferable:

docker run --rm -d --name bugboard-mcp `
  -p 127.0.0.1:18080:8000 `
  --mount "type=bind,src=C:\path\outside\repo\bugboard.env,dst=/run/secrets/bugboard.env,readonly" `
  -e BUGBOARD_SESSION_ENV=/run/secrets/bugboard.env `
  ghcr.io/bapho-bush/bugboard-mcp:latest

Security

Keep cookies, tokens, browser profiles, and authenticated request bodies out
of the repository. Publish a Docker HTTP port only to host loopback. Browser
requests with an Origin header must use an allowed origin.

License

This project is source-available under Apache-2.0 with Commons Clause
1.0. You may use, modify, and redistribute it, including for internal
commercial work. You may not sell the software itself or a product or service
whose value substantially comes from its functionality. It is not an
OSI-approved open-source license.