# 1. Clone the monorepo and enter this project
git clone https://github.com/VeritasPrime/Jose_Avengers.git
cd Jose_Avengers/sf-mcp-server

# 2. Install dependencies
uv sync

# 3. Configure credentials
cp .env.example .env       # then edit .env with the values below

# 4. Run the MCP server (stdio transport, default)
uv run python main.py

# Or run with SSE transport
MCP_TRANSPORT=sse uv run python main.py

# --- SF Tenant (VPMC Sandbox) ---
SF_API_HOST=https://api8preview.sapsf.com
SF_COMPANY_ID=VPMCSandbox
SF_USER_ID=<your-ias-user>
SF_PASSWORD=<your-ias-password>

# --- IAS / OIDC ---
IAS_HOST=abkakgd3p.accounts.ondemand.com
OIDC_CLIENT_ID=<oidc-client-id>
OIDC_CLIENT_SECRET=<oidc-client-secret>
IAS_DEPENDENCY_NAME=SF_DEPENDENCY

sf-mcp-server/
├── main.py                     # Entry point — creates FastMCP server, registers 52 tools
├── pyproject.toml              # Project config (uv/hatch)
├── uv.lock                     # Locked dependencies
├── .env                        # Credentials (NOT committed)
├── .mcp.json                   # MCP client config
├── CLAUDE.md                   # Claude Code project instructions
│
├── helpers/                    # Cross-cutting infrastructure
│   ├── credentials.py          # OIDC 2-step flow, token cache (per-tenant)
│   ├── credential_store.py     # Pluggable credential storage (env / GCP Secret Manager)
│   ├── sf_client.py            # Async OData client (DC resolution, Bearer auth, GET/POST/PUT/upsert)
│   ├── metadata_parser.py      # EDMX/CSDL XML → structured dicts (with SAP annotations)
│   ├── nl_query_parser.py      # Natural language → OData $filter (no LLM, pattern-based)
│   ├── template_parser.py      # CSV / Excel template parser for imports
│   ├── odata_utils.py          # OData helpers (escaping, pagination, etc.)
│   └── pii_filter.py           # PII redaction layer for tool outputs
│
├── models/                     # Pydantic v2 models (domain objects)
│   ├── rule_spec.py            # RuleSpec, RuleCondition, RuleAction, ExecutionNotes
│   ├── field_validation.py     # FieldValidationResult, ValidationReport, TestCase, TestMatrix
│   ├── employee.py             # EmployeeProfile, OrgNode, EmployeeComparison, EmployeeHistoryRecord
│   ├── organization.py         # FoundationObject, OrgUnit, PositionDetail
│   └── data_import.py          # ImportFieldValidation, ImportValidationReport, UpsertRecord, UpsertResult
│
├── tools/                      # 52 MCP tools, one file per category
│   ├── discovery.py            # Discovery (4)
│   ├── rule_generation.py      # Business Rules — generation (2)
│   ├── rule_documentation.py   # Business Rules — docs (2)
│   ├── employee.py             # Employee (5)
│   ├── organization.py         # Organization (3)
│   ├── configuration.py        # Configuration (2)
│   ├── data_import.py          # Data Import (3)
│   ├── analytics.py            # Analytics (3)
│   ├── instance_compare.py     # Instance Comparison (4)
│   ├── audit.py                # Audit & Troubleshooting (5)
│   ├── documentation.py        # Documentation (4)
│   ├── migration.py            # Migration (4)
│   ├── mdf.py                  # MDF Objects (3)
│   ├── golive.py               # Go-Live (2)
│   ├── country.py              # Country support (3)
│   └── workbook_generator.py   # Workbook Generator (3)
│
├── knowledge/                  # Static JSON knowledge base
│   ├── entity_mapping.json             # Entity catalog with NL hints, dating templates, codes
│   ├── workbook_entity_mapping.json    # Workbook → SF entity column mappings
│   ├── base_objects.json               # Base objects → primary OData entities
│   ├── rule_scenarios.json             # Standard SF rule scenarios
│   ├── event_types.json                # Event types (onSave, onChange, onInit, validate)
│   ├── best_practices.json             # SAP rule configuration best practices
│   └── pii_classification.json         # Field-level PII classification
│
├── docs/                       # Project documentation
│   ├── MCP_SF_Technical_Documentation.docx
│   ├── MCP_SF_Value_Proposition.md
│   ├── SF_Assistant_MCP_Value_Proposition.docx
│   └── superpowers/            # Specs and implementation plans
│
├── scripts/                    # Operational scripts (not MCP tools)
│   ├── generate_pptx.py
│   ├── generate_word_doc.py
│   └── validate_workbooks.py
│
├── tests/                      # pytest suite (uses respx for HTTP mocking)
│   ├── test_sf_client.py
│   ├── test_metadata_parser.py
│   ├── test_models.py
│   └── test_pii_filter.py
│
└── Workbooks Templates/        # Reference Excel templates from clients
    ├── 1_26 Version_ JVL - Employee Field Data & RBP.xlsx
    ├── 1_26 Version_ JVL - Workflow Notifications & Messages.xlsx
    └── 1_26 Version_JVL - Object & Picklist Data.xlsx

{
  "mcpServers": {
    "sf-assistant": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/absolute/path/to/Jose_Avengers/sf-mcp-server"
    }
  }
}

uv sync --dev          # install dev deps (pytest, pytest-asyncio, respx)
uv run pytest          # run all tests
uv run pytest -v       # verbose
uv run pytest tests/test_pii_filter.py -v   # one file

uv sync --extra frontend
cd frontend && npm install

GEMINI_API_KEY=...
GEMINI_MODEL=gemini-3-pro-preview
FRONTEND_BACKEND_PORT=8001
FRONTEND_CORS_ORIGIN=http://localhost:5173

# 1. Backend (FastAPI + SSE)
uv run python -m backend.app

# 2. Frontend (Vite)
cd frontend && npm run dev