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 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 is an architecture reference only: this package has no code, process, HTTP, or package dependency on it.

• mcp_identity owns the shared stdio, trusted-header HTTP, and OAuth identity mechanisms.

Related MCP server: Business Operations Agent Kit

Runtime baseline

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

/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 and the credential-email V1 contract 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 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.

{
  "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