CLAUDE.md•5.11 kB
# Project Overview
See @README for project overview
## Project Principles
1. **When anything is unclear, seems inconsistent, or is unsuitable to reach design goals: Stop and ask the user — never guess, assume, or silently default.**
- This applies at all stages: requirements, system design, and implementation.
- Always clarify technical ambiguities or specification gaps with a clear technical question.
2. **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
# MCP Servers
- **Serena**: Code analysis, navigation, and editing
- Use Serena for ALL codebase operations (finding/editing code, running tests, file operations)
- PREFER Serena's symbol tools (`find_symbol`, `find_referencing_symbols`) over reading entire files
- ALWAYS run tests using Serena's `execute_shell_command` after code changes
- **Context7**: External library documentation and examples
- ALWAYS use Context7 when looking up API signatures and documentation for libraries and frameworks
- Use Context7 FIRST to look up current examples
# Sources & Documentation
- **FastMCP framework**: https://gofastmcp.com/servers/server
- **BitSight API python library**: https://github.com/brandon-smith-187/bitsight
- **uv repository**: https://github.com/astral-sh/uv
- **uv docs**: https://docs.astral.sh/uv/
- **PEP723 spec**: https://peps.python.org/pep-0723/
- **uv implementation of PEP723**: https://docs.astral.sh/uv/guides/scripts/
# Workflow
You systematically develop following established project patterns and FastMCP framework compliance.
## Development Approach
1. **Requirements Analysis (THINK HARDER)**: Break down tasks into clear requirements, success criteria, quality gates, and constraints. It is essential to critically evaluate all requirements, assessing their feasibility and practicality in terms of framework and objective alignment. If you notice any inconsistencies or discrepancies, or when in ANY doubt, ALWAYS ASK the user using structured questions - DO NOT ASSUME OR GUESS.
2. **System Design (THINK HARDER)**: Identify required modules, interfaces, integrations, and resources before coding. Follow the project's library structure pattern.
3. **Implementation Strategy (THINK)**: Choose between TDD (when tests exist or explicitly requested) or direct development.
4. **Quality Assurance (THINK HARD)**: Verify against modular design principles and framework guidelines. Prefer running single tests, and not the whole test suite, for performance
### Question Format
**Question [X]: {Clear question statement}**
- **Options:** (up to 8 options max.)
- A) {Option 1 with brief explanation}
- B) {Option 2 with brief explanation}
- **Best Practice:** {Relevant FastMCP/Python development best practice}
- **Recommendation:** {Recommended option with reasoning}
## Project Principles
1. **When anything is unclear, seems inconsistent, or is unsuitable to reach design goals: Stop and ask the user — never guess, assume, or silently default.**
2. **Build a Minimal Viable Product (MVP) for personal use first — iterate and refine only if requested.**
## Communication Guideline
- Be direct and technical. No fluff - this is engineering, not marketing.
- Assume I understand common programming concepts without over-explaining
- Point out potential bugs, performance issues, or maintainability concerns
- Don't hedge criticism - Tell me if something is objectively bad and why
- Don't treat subjective preferences as objective improvements
Always think step-by-step through the development process, considering the project's goals, existing architecture, and framework limitations. Prefer editing existing files over creating new ones. Avoid making assumptions, collect veryfiable data instead.
## Testing and Development Commands
**Note**: All commands should be run from the project root directory.
### Running Tests
```bash
# Run all unit tests with uv (fast, with mocked dependencies)
uv run -m pytest tests/unit/ -v
# Run specific test file
uv run -m pytest tests/unit/test_company_search.py -v
# Traditional way (requires venv setup)
source .venv/bin/activate && BST_API_KEY="test-key" python -m pytest tests/unit/ -v
```
### Running the Server
```bash
# Run Birre with uv (easiest way - automatically installs dependencies)
uv run server.py
# Or run from GitHub
uvx --from git+https://github.com/boecht/birre server.py
# Development mode
source .venv/bin/activate && python -m src.birre.server
```
### Testing with Real API Key
```bash
# Test BitSight API connection with uv (uses user-exported BST_API_KEY)
uv run -c "import bitsight; print(f'✅ Found {len(bitsight.Companies().get_company_search(\"microsoft.com\"))} companies')"
```
### Key Environment Variables
- `BST_API_KEY` (required): Real BitSight API key of the user - should be exported in shell
- `DEBUG` (optional): Set to "true" for debug logging
The project requirements are documented in @requirements.md
