Skip to main content

MCP Capabilities Catalog

Source-backed guide for MCP prompts and resources in apps/backend/src/mcp/. Use this when changing assistant-facing shortcuts, static resources, or dynamic resource templates.

Intent​

MCP capabilities are split across:

  • backend handlers that register prompts and resources on each McpServer
  • shared catalog metadata in packages/global/consts/mcp-capabilities.consts.ts
  • PWA settings UI that presents the same capabilities to merchants

The shared catalog keeps names, labels, descriptions, and grouping aligned between backend and frontend. The backend still owns the executable prompt text and resource bodies.

Code map​

ConcernCodepathResponsibility
Shared metadatapackages/global/consts/mcp-capabilities.consts.tsPrompt and resource names, labels, descriptions, and display metadata
Prompt registrationapps/backend/src/mcp/infrastructure/mcp-prompts.handler.tsRegisters 8 merchant-facing prompt shortcuts on every MCP session
Resource registrationapps/backend/src/mcp/infrastructure/mcp-resources.handler.tsRegisters 3 static resources and 2 dynamic resource templates
Session wiringapps/backend/src/mcp/application/mcp-session.service.tsCreates per-session McpServer instances and calls the handlers
Merchant settings UIapps/frontend-pwa/src/pages/settings/mcp/Displays token setup and capability cards from the shared catalog

Runtime catalog​

Prompts​

McpPromptsHandler registers 8 prompt shortcuts:

  • daily_briefing
  • end_of_day_report
  • weekly_review
  • monthly_performance
  • low_stock_check
  • top_sellers
  • restock_plan
  • sales_by_location

Prompt descriptions come from MCP_PROMPT_CATALOG. The prompt bodies live in the handler because they include executable instructions for which tools to call and how to format merchant-facing output.

Resources​

McpResourcesHandler registers 5 resources total:

URITypeAppears in resources/list?Notes
flowpos://docs/quick-startStatic resourceYesAssistant capability summary and prompt shortcuts
flowpos://docs/prompt-guideStatic resourceYesDetailed prompt reference
flowpos://docs/currency-guideStatic resourceYesGuatemala currency, tax, FEL, and timezone context
flowpos://business/profileDynamic templateNoInstructs the assistant to call get_active_business for live data
flowpos://inventory/low-stockDynamic templateNoInstructs the assistant to call inventory tools for live data

The dynamic resources use new ResourceTemplate(..., { list: undefined }). That means clients should not expect them in resources/list, but can still read them by their known URI when the client supports URI-template resources.

Change workflow​

  1. Update MCP_PROMPT_CATALOG or MCP_RESOURCE_CATALOG when display metadata changes.
  2. Update McpPromptsHandler when prompt instructions or arguments change.
  3. Update McpResourcesHandler when resource body text, MIME type, or static vs dynamic behavior changes.
  4. Verify the PWA settings page still renders the shared catalog correctly.
  5. Add or update MCP E2E coverage for:
    • prompts/list
    • prompts/get
    • resources/list
    • resources/read

Keep tool behavior in tool classes and prompt/resource copy in the handlers. Do not document a prompt as performing an action unless its instructions call a tool that can perform that action for the current principal.

Common pitfalls​

  • resources/list returns only the 3 static resources. This is expected.
  • Resource templates are guidance resources; they do not fetch live business or inventory data by themselves.
  • Prompt names in the handler must match names exposed in shared catalog metadata, otherwise the PWA can advertise a shortcut that the MCP session does not register.
  • apps/backend/src/mcp/SYSTEM_PROMPT.md is not the runtime catalog. Treat the handlers and API reference as the source of truth for registered tools, prompts, and resources.