# Shayona Business Operations MCP

`mcp_shayona` is the standalone MCP service boundary for Shayona-specific business operations that do not belong in ERPNext transactional workflows. It is deliberately a capability service, not a second owner of Shayona data or a generic Frappe CRUD interface.

## Ownership and scope

- [`shayona`](../shayona) owns Shayona DocTypes, business data, hooks, and native Frappe permissions. This includes `Customer Service Credential`.
- `mcp_shayona` exposes bounded Shayona-specific MCP capabilities while executing as the authenticated Frappe user.
- [`mcp_erpnext`](../mcp_erpnext) is an architecture reference only: this package has no code, process, HTTP, or package dependency on it.
- [`mcp_identity`](../mcp_identity) owns the shared stdio, trusted-header HTTP, and OAuth identity mechanisms.

## Runtime baseline

The service runs with the existing Bench Python environment and MCP v1 line:

```text
/home/frappe/frappe-bench/env/bin/python -m mcp_shayona.mcp_server
```

It does not require `bench --site <site> install-app mcp_shayona`. The selected site must have the Shayona-owned `Customer Service Credential` DocType installed. The service validates live DocType metadata at tool execution time and fails closed when the schema is unavailable.

Backend selection is separate from transport: `MCP_BACKEND=direct` is the current
working backend, while `MCP_BACKEND=rest` is recognized but reserved and not
implemented. Do not configure REST yet. `MCP_TRANSPORT` only selects how the MCP
client communicates with this process (`stdio` or `streamable-http`).
See [the system design](docs/architecture/MCP_SHAYONA_SYSTEM_DESIGN.md) and the [credential-email V1 contract](docs/architecture/CREDENTIAL_EMAIL_V1.md) for the frozen boundaries.

## Public capabilities

The public inventory contains six credential tools and five Tea Entry tools:

- `search_customer_service_credentials`
- `get_customer_service_credential`
- `query_customer_service_credentials`
- `aggregate_customer_service_credentials`
- `prepare_customer_service_credential_email`
- `confirm_customer_service_credential_email`

- `get_tea_entry`
- `query_tea_entries`
- `aggregate_tea_entries`
- `create_tea_entry`
- `update_tea_entry`

Credential reads are bounded by role: search is fuzzy discovery, get is exact metadata lookup, query provides exact filtering with pagination and allowlisted sorting, and aggregate provides permission-aware count summaries. All read tools return only the fixed metadata projection. They never return, search, decrypt, filter, aggregate, or log `username` or `password`. Native Frappe read permissions remain authoritative.

See [operator commands](docs/COMMANDS.md) for stdio, trusted-header HTTP, and OAuth HTTP startup examples.

## Tea Entry operations

Tea Entry results expose only `name`, `date`, `no_of_cups`, `rate_per_cup`,
`total_amount`, and `vendor`. Reads and aggregation use native Frappe read
permissions. Create requires cups and an explicit rate; its omitted date uses the
Frappe server date. `total_amount` is controller-managed and read-only through MCP.
Create and update use native Frappe permissions; delete and cancel are not exposed.

## Credential email operation

Configure the non-secret business defaults in the active site's
`sites/<site>/site_config.json`, under the app-owned `mcp_shayona` namespace.
```json
{
  "mcp_shayona": {
    "business_defaults": {
      "version": 1,
      "credential_email": {
        "email_templates": {
          "cPanel": "Customer cPanel Credential Delivery",
          "Domain": "Customer Domain Credential Delivery"
        },
        "additional_note_variable": "additional_note"
      }
    }
  }
}
```

The two configured template names must exist as native Frappe `Email Template`
records, and each template body must contain the configured
`additional_note_variable`. Missing or malformed site configuration fails closed.
Do not use `common_site_config.json` for these business defaults.

The prepare tool returns a redacted preview and a 15-minute, single-use approval token.
After explicit user approval, confirm revalidates the credential, customer primary
email, authenticated operator email, template/configuration, and outgoing Email
Account before resolving username/password server-side. It renders the native template
and queues one email with the configured sender, required CC addresses, operator
Reply-To, and `redact_message_after_send=True`.

Secrets and the final rendered body never appear in MCP results, approval state, logs,
or errors. A successful result means `queued`, not delivered. No Communication
or File is created by this capability.

## License

MIT