# 🚀 FDIC BankFind MCP Server Standards

## 🚨 Prime Directives
1. **NO analysis paralysis** - Fix issues or request help after reasonable analysis
2. **Test-First Development** - Always write failing tests before implementation
3. **Minimal Viable Changes** - Implement the simplest solution that passes tests, then refactor

## 🦀 Rust Coding Standards
### Code Quality
- **MUST** pass `cargo check` and `cargo test`
- **MUST** use idiomatic Rust patterns
- **MUST** use explicit error handling (`Result`, `Option`)
- **MUST** validate all user inputs
- **MUST** document all public items with `///` doc comments

### Naming Conventions
- `snake_case` for functions and variables
- `CamelCase` for types, structs, and enums
- `SCREAMING_SNAKE_CASE` for constants

## 📁 File Organization
### Imports (Top of File)
```rust
// 1. Standard library
use std::collections::HashMap;

// 2. Crate-local
use crate::config::FdicApiConfig;

// 3. External crates (alphabetized)
use axum::{extract::{Query, State}, http::StatusCode, response::IntoResponse};
use serde::{Deserialize, Serialize};
use utoipa::{IntoParams, ToSchema};
```

### Code Structure
1. Type Definitions
   - Internal types
   - Public types
2. `main()` function
3. Public functions (alphabetical)
4. Private helper functions (alphabetical)

## 🌐 Web/API Standards
### Axum 0.7+ Patterns
- Use `axum` 0.7+ idioms
- Validate all inputs
- Standard response format: `{ meta, data }`
- Error Handling:
  - 400 for client errors
  - 502 for upstream errors

## 🧪 Testing Requirements
### Unit Tests
- **REQUIRED** for all new features and public types
- **MUST** cover:
  - Happy paths
  - Error cases
  - Edge cases
- **MUST** use mocks for external services
- **MUST** be updated with code changes

## 🔄 Project Workflow
1. Branch Naming: `GH-<issue-number>_<ProperCaseSummary>` (e.g., `GH-9_EndToEndIntegrationTest`)
2. Code Review:
   - All PRs require review
   - All tests must pass
   - Code coverage must not decrease
3. Documentation:
   - Update relevant docs with changes
   - Add examples for new features

## 🏦 Project-Specific Rules
- MCP endpoints must:
  - Proxy all relevant FDIC BankFind API parameters
  - Uppercase all string parameters (except `api_key` and `filename`)
  - Validate all inputs
  - Use consistent error formats
- Use `// TODO:` comments for temporary workarounds
- Document architectural decisions

## 🔄 Continuous Improvement
- Regularly review and update these standards
- Document new patterns and conventions
- Remove deprecated patterns