BitSight Community MCP Server

# CoPilot Instructions This document contains the full Agent Operations Guide for BiRRe. ## Agent Operations Guide This guide aligns LLM agents with BiRRe workflows. Skim section 2 for philosophy, section 3 for day-to-day execution, and section 5 for the commands you will run most often ## 1. Orientation & Reference Docs ### Quick Links - Project Overview: [README.md](../README.md) - Changelog: [CHANGELOG.md](../CHANGELOG.md) - Changelog Standards: [edit-changelog.instructions.md](instructions/edit-changelog.instructions.md) - Project Architecture: [ARCHITECTURE.md](../docs/ARCHITECTURE.md) - BitSight API v1 Reference: [bitsight.v1.overview.md](../docs/apis/bitsight.v1.overview.md) - BitSight API v2 Reference: [bitsight.v2.overview.md](../docs/apis/bitsight.v2.overview.md) - FastMCP framework: <https://gofastmcp.com/servers/server> ## 2. Core Principles ### Project Principles 1. **Ground every statement in current evidence.** - Inspect the live repo/docs/logs before forming an opinion or recommending a change - Cite the exact file/line that supports your conclusion so nothing relies on memory or stale data 2. **Clarify, don’t guess** - Whenever something is unclear, inconsistent, or blocking the design goal, pause and ask the user a precise technical question instead of assuming or defaulting - Only follow a different approach if the prompt/mode explicitly demands it - Apply this discipline across all stages; requirements, system design, and implementation alike - Turn every ambiguity or spec gap into a targeted clarification - Treat uncertainty signals like "I think", "probably", or "maybe" as red flags that require clarification 3. **Build a Minimal Viable Product (MVP) for personal use first — iterate and refine only if requested.** - Prioritize functionality and stability over broad compatibility - Avoid premature optimization for universal use cases 4. **Quality and architecture trump backwards compatibility.** - Breaking changes are acceptable if they improve the codebase - Remove outdated patterns immediately; do not preserve legacy code - Avoid shortcuts; build the right solution once - Clean, maintainable architecture outranks legacy API stability 5. **Documentation focuses on user value, not internal implementation.** - CHANGELOG entries describe user benefits using .github/instructions/edit-changelog.instructions.md - Highlight impact (reliability, performance, UX) instead of internal codes (TD-XXX, QA-XXX) - Keep technical specifics in commits and internal tracking - Example: - ❌ "Refactored 7 functions to reduce complexity (TD-003)" - ✅ "Enhanced reliability through simplified error handling" ### Documentation Principles - **Code Comments (implementation-facing)** - See [Python Style Instructions](instructions/edit-python.instructions.md) for editing-time guidance. ## 3. Standard Workflow ### Development Approach - **Requirements Analysis** - Break down tasks into clear requirements, success criteria, and constraints - Evaluate feasibility with respect to FastMCP capabilities and project architecture - When uncertain, ask using the structured format - **System Design** - Identify required modules, interfaces, integrations, and resources before coding - Map changes to FastMCP hybrid architecture components - **Implementation Strategy** - Choose TDD when tests exist or are requested - Otherwise implement directly, component by component, leveraging FastMCP auto-generation - **Quality Assurance** - Check against modular design principles, FastMCP compliance, and framework guidelines - Prefer targeted tests over full suite runs for speed ### Development Best Practices - Think step-by-step about goals, architecture, and limitations - Prefer editing existing files over creating new ones - Verify assumptions with data; never guess - Run the smallest relevant tests for rapid feedback - Execute pertinent tests after every change to catch regressions early ### Commit Practices #### When You Finish a Task 1. Stage every file you changed for that task (`git add <paths>` or `git add -p`) 2. Stop. Do not commit; wait for the user to review or adjust #### Safety and Etiquette - Never push or merge to protected branches (`main`, `release/*`) unless the user explicitly instructs you to - If user’s adjustments introduce conflicts or inconsistent staging, pause and clarify how to proceed before committing ### Quality Assurance Checklist - Validate outputs against the original task description before finalizing - Confirm tests were run (or explain why they were skipped) and record outcomes - Ensure documentation and comments reflect any significant behaviour changes - Cross-check that FastMCP integration points remain consistent ## 4. Communication Protocol ### Messaging Guidelines - Be direct and technical; prioritize facts over tone - Assume core programming literacy; skip over-explaining basics - Flag bugs, performance issues, or maintainability risks immediately - State opinions as such; do not present subjective preferences as facts ### Structured Clarification Requests When asking the user for clarification, follow this template: ```text **Question X**: {Clear, specific question} **Options**: - A) {Option with trade-offs} - B) {Option with trade-offs} - C) {Additional options as needed} **Context**: {Relevant best practices or constraints} **Recommendation**: {Your recommendation with reasoning} ``` ## 5. Tooling & Runtime ### Environment Requirements - BiRRe requires **Python 3.13** or later. Install via uv if unavailable: ```bash uv python install 3.13 ``` ### Testing Commands uv automatically installs the correct Python version, and dependencies such as FastMCP. If BiRRe runs, FastMCP is present. Assume a BitSight API key is available via `BITSIGHT_API_KEY` or local config. With either configured, it is safe—and recommended—to run online tests. - Full suite (preferred): ```bash uv run pytest ``` - Offline only: ```bash uv run pytest --offline ``` - Online only: ```bash uv run pytest --online-only ``` ### Server Operations - Run BiRRe locally (auto-installs dependencies): ```bash uv run birre ``` - FastMCP smoke test with timeout: ```bash timeout 15s uv run birre || echo "✅ Server test completed" ``` ## 6. Model-Specific Addenda ### Claude-Specific Requirements **If you are powered by Anthropic's Claude model, follow these mandatory requirements:** #### CRASH Tool Usage Use the CRASH tool (structured reasoning) for all multi-step tasks, including: - Tasks requiring clarifying questions to the user - Multi-step analysis, review, or planning tasks - Code refactoring or architectural changes - Bug investigation and fixes (beyond trivial typos) - Feature implementation requiring multiple components - Documentation updates (even single files with multiple sections) - Version migrations or dependency updates **Workflow**: Plan (step 1-2) → Execute one step at a time (step 3-N) → Final QA (last step) **CRASH Features to Leverage**: - Use `revises_step` to correct mistakes in earlier reasoning - Use `branch_from` to explore alternative approaches - Track `confidence` and `uncertainty_notes` when facing ambiguous situations **If CRASH tool is unavailable**: Refuse to proceed on multi-step tasks Ask the user to install the CRASH MCP server from <https://github.com/nikkoxgonzales/crash-mcp> #### Mandatory QA Step Every task must end with a QA review that compares all work to the initial task: 1. **Restate original task**: What did the user ask for? 2. **List file changes**: For each modified file, explain how the change serves the original task 3. **Identify misalignment**: Call out any changes that don't directly serve the task objective 4. **Reflect on alignment**: Does the complete set of changes accomplish what was requested? Are there gaps or overreach? 5. **Verify changes**: Read back edited content to confirm correctness ## 7. Appendix ### FastMCP Resources - FastMCP framework documentation: <https://gofastmcp.com/servers/server>