BiRRe

BiRRe (Bitsight Rating Retriever) is a Model Context Protocol (MCP) server that turns a BitSight subscription into LLM-friendly tools. It hides 400+ raw endpoints behind a curated, strongly-typed workflow surface, handles ephemeral subscriptions automatically, and ships as a zero-install uv app so analysts and agents can run it anywhere.

Why use BiRRe?

• Unified workflows – LLMs gain one consistent toolset for search, ratings, onboarding, and subscription hygiene.
• Safer operations – automatic folder targeting, dry-run previews, and retry-aware helpers keep BitSight data tidy while preventing accidental churn.
• Trustworthy releases – strict typing (pyright), property-based tests, signed artifacts, and SBOMs make it easy to depend on BiRRe in regulated environments.

What you need

Quick start

1. Export your BitSight API key.

2. Start the MCP server with uvx (install-free PyPI run):

   export BITSIGHT_API_KEY="your-bitsight-api-key"
   uvx birre
   

3. Point your MCP-compatible client/LLM at the server endpoint. Start with company_search to obtain GUIDs, then call get_company_rating or run the risk-manager workflows.

4. Use --help for every available command, subcommand, and option.

The rest of this README assumes a local checkout: Create a local copy with git clone https://github.com/boecht/birre, then start with uv run birre in the BiRRe directory.

Configuration

Configuration layers merge in this order: config.toml → config.local.toml → environment variables → CLI flags. Inspect or validate the effective settings with:

uv run birre config show
uv run birre config validate --config differently/named/config.toml

See docs/CLI.md for full option tables and config.toml for annotated defaults.

Tooling overview

Switch contexts via --context, BIRRE_CONTEXT, or [runtime].context. Tool names map directly to MCP tool calls.

Shared tools (standard + risk_manager)

risk_manager-only tools

Self-test

Use the built-in self test to sanity-check your setup before connecting a client. The command mirrors the run startup sequence, reports the resolved configuration, and exercises BitSight connectivity, subscription, and tooling checks against BitSight’s testing environment (staging). When invoked with --offline, only the local configuration and logging checks run.

# Run the full diagnostics against the default BitSight testing endpoint.
uv run birre selftest

# Target the production API to exercise real subscription logic and permissions.
uv run birre selftest --production

Successful runs exit with 0. Failures return 1, and partial results with warnings (for example, optional tooling gaps in offline mode) return 2. Expect occasional 403 Access Denied responses when using BitSight’s testing environment.

Documentation, support & contributions

• docs/CLI.md – full command reference, configuration helpers, option tables.
• docs/ROADMAP.md – current release summary plus upcoming milestones.
• docs/ARCHITECTURE.md – FastMCP layering and BitSight integration design.
• docs/SECURITY_VERIFICATION.md – verifying signed releases (Sigstore, SBOM, PyPI).
• docs/apis/ – curated BitSight endpoint overviews (v1/v2).
• CONTRIBUTING.md – development workflow, pytest/pyright instructions, PR expectations.
• SECURITY.md – reporting process and supported-release policy.

Issues and PRs are welcome; contributions are released under the Unlicense.

Disclaimer

BiRRe (Bitsight Rating Retriever) is not affiliated with, endorsed by, or sponsored by BitSight Technologies, Inc.

• This project is developed and maintained independently by the open source community
• "Bitsight" is a registered trademark of BitSight Technologies, Inc.
• This integration is provided "as-is" without any warranty or official support from BitSight Technologies, Inc.
• Use is intended for integration scenarios respecting BitSight’s terms.