# Shayona Business Operations MCP

`mcp_shayona` is a standalone MCP service for Shayona-specific operational
workflows that do not belong in the ERPNext transactional-domain MCP service.
The package is currently foundation-only: it exposes no business tools and
does not yet send credential emails.

## Scope

This project will provide narrowly bounded, typed MCP capabilities over
business data owned by the installed site applications. The first planned
capability is an approval-bound, redacted-preview workflow for delivering a
customer service credential by email.

It is not a generic Frappe CRUD gateway, an ERPNext Sales/Purchase/Accounts
server, an identity provider, or a replacement for native Frappe permissions.
The service will not expose usernames or decrypted passwords in MCP results,
previews, errors, logs, traces, or approval state.

## Application boundaries

- `shayona` owns the Shayona business DocTypes and data, including
  `Customer Service Credential`. `mcp_shayona` consumes that data through
  Frappe APIs and native permission checks; it does not recreate the DocType.
- `mcp_erpnext` owns bounded ERPNext transactional capabilities. It is a
  reference-only architecture source for this project and is not a runtime,
  HTTP, import, or package dependency of `mcp_shayona`.
- `mcp_identity` owns shared MCP authentication-mode and Frappe identity
  primitives. `mcp_shayona` imports that existing Python package from the
  Bench environment; it does not copy or redesign the identity implementation.

## Standalone runtime

`mcp_shayona` is a Bench/Python package and standalone MCP process, not a
site-installed business app. Its future server entrypoint will explicitly
select a site, call `frappe.init(site=..., sites_path=..., force=True)`,
connect, resolve the authenticated Frappe user through `mcp_identity`, call
`frappe.set_user()`, and then execute typed capabilities. The target site must
not require `bench --site <site> install-app mcp_shayona`; the app is not
listed in the site's installed-app list and Task 01 adds no hooks, DocTypes,
patches, fixtures, or scheduled jobs needed at runtime.

For HTTP, the service will preserve the verified `mcp_identity` model:
trusted-header mode validates a server-only Bearer secret and resolves the
request's `X-MCP-User-Email` to an enabled non-Guest Frappe User; OAuth mode
uses the native Frappe opaque token's subject and never falls back to headers,
the stdio user, or a shared secret. Frappe authorization remains authoritative
after identity resolution.

## MCP SDK baseline

The official MCP Python SDK verified for this task is `mcp 2.2.0`, released on
2026-09-07. The package constraint is `mcp>=2.2,<3`: it starts on the current
stable v2 line while preventing an unreviewed future major upgrade. New
implementation must use the v2 `MCPServer` API and its current transport/auth
APIs. It must not copy `mcp_erpnext`'s legacy `mcp>=1.0,<2.0` constraint or the
removed `mcp.server.fastmcp.FastMCP` import path.

References: [official v2 SDK](https://github.com/modelcontextprotocol/python-sdk),
[v2.2.0 release](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.2.0),
and [v1-to-v2 migration guide](https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/migration.md).

## Documentation

- [System design](docs/architecture/MCP_SHAYONA_SYSTEM_DESIGN.md)
- [Credential email V1 contract](docs/architecture/CREDENTIAL_EMAIL_V1.md)
- [Foundation task](docs/architecture/01_TASK_MCP_SHAYONA_FOUNDATION_AND_SYSTEM_DESIGN.md)

## License

MIT