OSIT-AE-API-FastAPI/documentation/archive/SCOPE__MCP_FIELD_MANAGER.md

Scope: Automated Field Management Tool (MCP)

Task ID: 153357623 Type: MCP Tool / Dev Utility Target System: Aether API V3 (FastAPI + MariaDB)

1. Objective

To create a safe, automated "Vertical Slice" tool that handles the repetitive and error-prone process of adding or modifying fields in the Aether backend.

Current Manual Process (Pain Points):

1. ALTER TABLE in MariaDB (risk of locking or syntax errors).
2. Update/Recreate v_[object] SQL View (easy to forget, breaks Triple ID).
3. Update Pydantic Models in app/models/ (tedious, risk of schema drift).
4. Update searchable_fields in app/object_definitions/ (often forgotten).

2. Proposed Solution: ae_field_manage

A Python script in the MCP toolset (agents_sync/scripts/ae_field_manage.py) that orchestrates these steps atomically.

Usage Example

# CLI Usage
python3 ae_field_manage.py add person nickname --type string --length 50 --nullable

# MCP Tool Usage
{
  "tool": "ae_field_manage",
  "action": "add",
  "object": "person",
  "field": "nickname",
  "params": { "type": "string", "length": 50 }
}

3. Implementation Steps

Phase 1: Analysis & Safety (Dry Run)

• Input Validation: Ensure field name is snake_case and valid.
• Schema Check: Check if field already exists in DB or Pydantic.
• Impact Analysis: Identify which files will be modified (e.g., app/models/person_models.py).

Phase 2: Database Operations

• Backup: (Optional) Trigger a quick table dump?
• DDL Execution: Run ALTER TABLE {table} ADD COLUMN {field} {type} ....
• View Recreation:
  • Fetch current view definition OR construct standard V3 view.
  • Ensure Triple ID pattern is preserved (id, {type}_id, {type}_id_random).
  • Execute CREATE OR REPLACE VIEW.

Phase 3: Codebase Modification (AST/Regex)

• Pydantic Model Update:
  • Locate class {Object}_Base(BaseModel):.
  • Inject field definition: nickname: Optional[str] = Field(None, max_length=50).
  • Use AST (Abstract Syntax Tree) parsing for safety, or careful Regex if AST is too complex for simple insertions.
• Search Registry Update:
  • If flag --searchable is set, add to searchable_fields list in app/object_definitions/core.py.

Phase 4: Verification

• Integrity Check: Run ae_check_integrity to verify View health.
• Schema Sync: Trigger ae_schema_sync to update Frontend TS interfaces (if applicable).

4. Technical Constraints

• Database: MariaDB 10.11.
• Language: Python 3.10+.
• ORM: SQLAlchemy (for type mapping), but raw SQL for DDL.
• File Paths: Must respect ~/OSIT_dev/ structure.

5. Risks & Mitigation

• Risk: Corrupting person_models.py.
  • Mitigation: Create a .bak copy before writing.
• Risk: Locking the DB table.
  • Mitigation: Verify no active heavy transactions (low priority for dev env).
• Risk: View definition divergence.
  • Mitigation: The tool should ideally read the existing view logic or use a standard template.

6. Definition of Done

• Can add a string/int/bool field to person via one command.
• Database column exists.
• View v_person includes the column.
• Person_Base model includes the field.
• ae_obj_info person reflects the change.