# DataChef Full Agent Guide

DataChef lets AI agents discover data sources, plan bounded queries, run and profile query results, generate Smart Forms, and return UI-ready display cards while keeping operator approval and scoped tokens in the loop.

## Public discovery
- `/llms.txt`: compact AI-agent summary.
- `/llms-full.txt`: this full guide.
- `/openapi.json`: OpenAPI 3.1 description for public discovery and MCP JSON-RPC entry points.
- `/.well-known/mcp.json`: MCP client discovery document.

## Base URLs
- Public origin: https://chef.threatco.io
- MCP endpoint: https://chef.threatco.io/api/mcp
- MCP transport: streamable-http-json
- Agent console: https://chef.threatco.io/agents

## Authentication
When production exposure is enabled, the discovery documentation URLs are intentionally unauthenticated. While `DATACHEF_ENABLE_PROD_EXPOSURE` is unset/false on `chef.threatco.io`, the production-host lock returns 503 for discovery docs too; that means DataChef is intentionally disabled, not that MCP discovery is malformed. Runtime DataChef operator surfaces stay behind app authentication. The MCP endpoint is public at the network layer but rejects every runtime call without a bearer token created from the authenticated `/agents` console.

Production operator login uses Azure AD B2C:
- Login page: https://chef.threatco.io/login
- Login start route: https://chef.threatco.io/auth/login
- B2C tenant name: jsraauth
- B2C authority: https://jsraauth.b2clogin.com/jsraauth.onmicrosoft.com/B2C_1_SIGNUP_SIGNIN
- Redirect URI to register in B2C: https://chef.threatco.io/auth/callback
- Post logout URI to register in B2C: https://chef.threatco.io/auth/signed-out
- Production fail-closed setting: `DATACHEF_AUTH_MODE=b2c` and `DATACHEF_REQUIRE_B2C=true`
- Production exposure switch: keep `DATACHEF_ENABLE_PROD_EXPOSURE` unset/false until security readiness is verified.
- Default super-admin pin: `jaskaranz@gmail.com` uses B2C object ID `472818ce-c23f-425f-96a4-31d3e60d82e1` from the production debt-app `ExternalAuthId`.
- Production readiness also requires app-only Microsoft Graph user listing credentials and `DATACHEF_DELETE_B2C_ACCOUNT=true` so the super-admin user list and self-service B2C account deletion are real. Use `DATACHEF_SUPER_ADMIN_OIDS` only to add or override admin object IDs.
- Agents should read `/api/admin/users` `superAdminGraphLookup.objectId` to confirm the live Microsoft Graph object ID for `jaskaranz@gmail.com` before opening production exposure.
- Account self-management: https://chef.threatco.io/account
- Account export API: https://chef.threatco.io/api/account/export
- Account delete API: `DELETE https://chef.threatco.io/api/account` with `confirmEmail` in the query string, JSON body, or form body. The JSON response includes `logoutUrl`; browser form deletion redirects through `/logout` so the B2C browser session is also ended.
- Deleted local accounts are not automatically recreated by later B2C sign-in. Deleted/stale sessions return `403 account_deleted` on APIs or route to `/auth/error?error=account_deleted` on pages until a super admin intentionally restores access.
- User webhook summaries: https://chef.threatco.io/api/webhooks
- Inbound webhook delivery: `POST https://chef.threatco.io/api/ingest/webhook/{slug}` with `Authorization: Bearer <webhook-secret>`, `x-datachef-webhook-secret`, or HMAC `x-datachef-signature`. Replay protection is per B2C user and connector; send a stable event ID such as `x-datachef-event-id`, `x-webhook-id`, `x-event-id`, `x-github-delivery`, or payload `id`. Duplicate IDs inside the connector TTL return HTTP 409.
- Super-admin users and auth readiness: https://chef.threatco.io/admin/users

Use the smallest useful scope:
- `mcp:read`: manifests, catalogs, display helpers, read-only metadata.
- `mcp:query`: query planning, query execution, source inspection, Smart Forms generation.
- `mcp:execute`: bounded Smart Form action execution.
- `mcp:mutate`: saving recipes, publishing forms, confirmed mutations.
- `mcp:admin`: reserved for administrative MCP operations.

## Generic HTTP MCP client config
```json
{
  "mcpServers": {
    "datachef": {
      "url": "https://chef.threatco.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${DATACHEF_MCP_TOKEN}"
      }
    }
  }
}
```

## JSON-RPC examples

Initialize:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}
```

List tools:
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
```

Run a bounded query:
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "datachef.query.run",
    "arguments": {
      "lang": "sql",
      "queryText": "SELECT * FROM source_rows LIMIT 100",
      "sources": [
        {
          "sourceType": "dataset",
          "sourceId": "demo_b2c_users",
          "alias": "source_rows"
        }
      ]
    }
  }
}
```

## Resources
- `datachef://docs/query-guide` - Super Query Guide: How agents should discover, plan, run, profile, explain, and save DataChef queries.
- `datachef://docs/smart-forms-guide` - Smart Forms Guide: How agents inspect sources, generate, validate, publish, and run definition-driven forms.
- `datachef://docs/display-guide` - MCP Display Guide: How agents return Adaptive Card-style JSON blocks for metrics, summaries, and tables.
- `datachef://sources/catalog` - Source Catalog: Runtime catalog of queryable DataChef sources.
- `datachef://forms/catalog` - Smart Forms Catalog: Runtime catalog of saved Smart Forms, source coverage, statuses, and share links.
- `datachef://forms/components` - Smart Forms Component Registry: Allowed Smart Forms components grouped by basic, advanced, and operational controls.
- `datachef://docs/security-model` - MCP Security Model: Authentication, scoped tokens, destructive confirmations, and audit behavior.

## Prompts
- `explore_data` - Explore Data: Discover sources, plan a bounded query, run it, and profile the results.
- `join_sources` - Join Sources: Build a federated query plan across multiple DataChef sources.
- `profile_dataset` - Profile Dataset: Profile a dataset and summarize useful fields and chart hints.
- `save_query_recipe` - Save Query Recipe: Turn a validated query plan into a reusable DataChef recipe.
- `investigate_api_service` - Investigate API Service: Inspect API service metadata and use API security runs where permits allow.
- `generate_smart_form` - Generate Smart Form: Inspect a source and generate a definition-driven operator form.
- `rescue_legacy_ui` - Rescue Legacy UI: Turn a raw API, DB table, or dataset into a sane Smart Form workflow.
- `present_results` - Present Results: Convert grounded query, profile, or source evidence into UI-ready display cards.

## Tools
### datachef.display.card
- Title: Build a display card
- Group: display
- Scope: mcp:read
- Risk: read
- Description: Return validated Adaptive Card-style JSON for summary, metric, or table displays. Use this when an agent needs structured UI instead of markdown.
- Input schema: `{"type":"object","properties":{"kind":{"type":"string","enum":["summary","metrics","table"]},"title":{"type":"string"},"subtitle":{"type":"string"},"facts":{"type":"array"},"metrics":{"type":"array"},"columns":{"type":"array"},"rows":{"type":"array"},"maxRows":{"type":"number"}}}`
- Example: `{"kind":"metrics","title":"Source inventory","metrics":[{"label":"Datasets","value":11},{"label":"Connectors","value":7}]}`

### datachef.display.table
- Title: Build a display table
- Group: display
- Scope: mcp:read
- Risk: read
- Description: Return a bounded Adaptive Card-style table JSON block from columns and rows.
- Input schema: `{"type":"object","required":["columns","rows"],"properties":{"title":{"type":"string"},"columns":{"type":"array"},"rows":{"type":"array"},"maxRows":{"type":"number"}}}`
- Example: `{"title":"Display names","columns":["displayName"],"rows":[["unknown"],["Ken Zhou"]]}`

### datachef.operator.delete_api_service
- Title: Delete API service
- Group: operator
- Scope: mcp:mutate
- Risk: destructive
- Description: Delete an API service registry entry. Requires confirm=true.
- Input schema: `{"type":"object","required":["id","confirm"],"properties":{"id":{"type":"string"},"confirm":{"type":"boolean"}}}`
- Example: `{"id":"service_id","confirm":true}`

### datachef.operator.delete_connector
- Title: Delete connector
- Group: operator
- Scope: mcp:mutate
- Risk: destructive
- Description: Delete a connector and its linked datasets. Requires confirm=true.
- Input schema: `{"type":"object","required":["id","confirm"],"properties":{"id":{"type":"string"},"confirm":{"type":"boolean"}}}`
- Example: `{"id":"connector_id","confirm":true}`

### datachef.operator.delete_dataset
- Title: Delete dataset
- Group: operator
- Scope: mcp:mutate
- Risk: destructive
- Description: Delete a DataChef dataset. Requires confirm=true.
- Input schema: `{"type":"object","required":["id","confirm"],"properties":{"id":{"type":"string"},"confirm":{"type":"boolean"}}}`
- Example: `{"id":"dataset_id","confirm":true}`

### datachef.forms.check_drift
- Title: Check Smart Form source drift
- Group: smart-forms
- Scope: mcp:query
- Risk: read
- Description: Compare a saved Smart Form definition with the current source shape and return added, removed, and changed fields.
- Input schema: `{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"persist":{"type":"boolean"}}}`
- Example: `{"id":"form_id","persist":true}`

### datachef.forms.discover
- Title: Discover Smart Forms
- Group: smart-forms
- Scope: mcp:read
- Risk: read
- Description: List Smart Forms, source coverage, modes, published links, intelligence scores, and available definition-driven form workflows.
- Input schema: `{"type":"object","properties":{}}`
- Example: `{}`

### datachef.forms.generate
- Title: Generate a Smart Form definition
- Group: smart-forms
- Scope: mcp:query
- Risk: execute
- Description: Generate a schema-validated Smart Form definition from source inspection, with grouped fields, components, actions, critique, and intelligence score.
- Input schema: `{"type":"object","required":["sourceType","sourceId"],"properties":{"sourceType":{"type":"string"},"sourceId":{"type":"string"},"name":{"type":"string"},"mode":{"type":"string"}}}`
- Example: `{"sourceType":"dataset","sourceId":"demo_b2c_users","name":"B2C User Rescue Form"}`

### datachef.forms.inspect_source
- Title: Inspect a form source
- Group: smart-forms
- Scope: mcp:query
- Risk: execute
- Description: Inspect a dataset, connector resource, API endpoint, or query recipe and return fields, samples, risks, lookup candidates, and repair suggestions.
- Input schema: `{"type":"object","required":["sourceType","sourceId"],"properties":{"sourceType":{"type":"string","enum":["dataset","connector","api-service","recipe"]},"sourceId":{"type":"string"},"resource":{"type":"string"},"endpointPath":{"type":"string"},"method":{"type":"string"},"rowLimit":{"type":"number"}}}`
- Example: `{"sourceType":"dataset","sourceId":"demo_b2c_users","rowLimit":50}`

### datachef.forms.publish
- Title: Publish a Smart Form
- Group: smart-forms
- Scope: mcp:mutate
- Risk: mutate
- Description: Publish a Smart Form as a locked version with DataChef URI and live route.
- Input schema: `{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"confirm":{"type":"boolean"}}}`
- Example: `{"id":"form_id","confirm":true}`

### datachef.forms.regenerate
- Title: Regenerate Smart Form draft
- Group: smart-forms
- Scope: mcp:mutate
- Risk: mutate
- Description: Regenerate a saved Smart Form draft from the current source shape while preserving published versions.
- Input schema: `{"type":"object","required":["id","confirm"],"properties":{"id":{"type":"string"},"confirm":{"type":"boolean"}}}`
- Example: `{"id":"form_id","confirm":true}`

### datachef.forms.run
- Title: Run a Smart Form action
- Group: smart-forms
- Scope: mcp:execute
- Risk: execute
- Description: Run a read/search/execute Smart Form action. Mutation actions require confirm=true and existing action permits.
- Input schema: `{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"actionId":{"type":"string"},"filters":{"type":"object"},"values":{"type":"object"},"confirm":{"type":"boolean"}}}`
- Example: `{"id":"form_id","filters":{"status":"active"}}`

### datachef.forms.validate
- Title: Validate a Smart Form definition
- Group: smart-forms
- Scope: mcp:query
- Risk: read
- Description: Validate a Smart Form definition for component registry, sections, safe action bindings, and mutation confirmation boundaries.
- Input schema: `{"type":"object","required":["definition"],"properties":{"definition":{"type":"object"}}}`
- Example: `{"definition":{"id":"form_id"}}`

### datachef.query.explain
- Title: Explain query execution
- Group: super-query
- Scope: mcp:query
- Risk: execute
- Description: Explain rendered query, source bindings, execution mode, bytes/rows scanned, warnings, and citations.
- Input schema: `{"type":"object","properties":{"queryText":{"type":"string"},"sources":{"type":"array"},"recipeId":{"type":"string"}}}`
- Example: `{"queryText":"SELECT * FROM source_rows LIMIT 20","sources":[{"sourceType":"dataset","sourceId":"demo_b2c_users","alias":"source_rows"}]}`

### datachef.query.plan
- Title: Plan a bounded query
- Group: super-query
- Scope: mcp:query
- Risk: read
- Description: Create a deterministic query plan with source bindings, query text, risks, variables, and the next runnable call.
- Input schema: `{"type":"object","properties":{"objective":{"type":"string"},"selectedSources":{"type":"array"},"rowLimit":{"type":"number"},"lang":{"type":"string","enum":["sql","kql"]},"constraints":{"type":"array","items":{"type":"string"}}}}`
- Example: `{"objective":"Show recent rows","selectedSources":[{"sourceType":"dataset","sourceId":"demo_b2c_users","alias":"source_rows"}]}`

### datachef.query.profile
- Title: Profile query results
- Group: super-query
- Scope: mcp:query
- Risk: execute
- Description: Run a bounded query and return field profile metrics, chart hints, warnings, truncation state, and citations.
- Input schema: `{"type":"object","properties":{"queryText":{"type":"string"},"sources":{"type":"array"},"rowLimit":{"type":"number"}}}`
- Example: `{"queryText":"SELECT * FROM source_rows LIMIT 100","sources":[{"sourceType":"dataset","sourceId":"demo_nginx_ecommerce_logs","alias":"source_rows"}]}`

### datachef.query.run
- Title: Run a bounded super query
- Group: super-query
- Scope: mcp:query
- Risk: execute
- Description: Execute SQL/KQL/recipe/federated queries over DataChef datasets and live connector sources.
- Input schema: `{"type":"object","required":["queryText"],"properties":{"lang":{"type":"string","enum":["sql","kql"]},"queryText":{"type":"string"},"recipeId":{"type":"string"},"sources":{"type":"array"},"variables":{"type":"object"},"timeWindow":{"type":"string"},"rowLimit":{"type":"number"}}}`
- Example: `{"lang":"sql","queryText":"SELECT * FROM source_rows LIMIT 100","sources":[{"sourceType":"dataset","sourceId":"demo_b2c_users","alias":"source_rows"}]}`

### datachef.query.save_recipe
- Title: Save query recipe
- Group: super-query
- Scope: mcp:mutate
- Risk: mutate
- Description: Save an approved query plan as a DataChef query recipe with variables and time-window defaults.
- Input schema: `{"type":"object","required":["queryText"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"queryText":{"type":"string"},"sources":{"type":"array"},"variables":{"type":"array"}}}`
- Example: `{"name":"Agent B2C sample","queryText":"SELECT * FROM source_rows LIMIT 100","sources":[{"sourceType":"dataset","sourceId":"demo_b2c_users","alias":"source_rows"}]}`

### datachef.sources.discover
- Title: Discover queryable DataChef sources
- Group: super-query
- Scope: mcp:read
- Risk: read
- Description: List datasets, connectors, API services, recipes, schemas, capabilities, row limits, and supported query modes.
- Input schema: `{"type":"object","properties":{}}`
- Example: `{}`