{ "schemaVersion": 1, "kind": "recipe", "slug": "resources-and-prompts", "title": "Teach agents how your app works without pasting the manual into every result.", "searchTitle": "Add MCP Resources, prompts and usage instructions to a Supabase Chumbo server", "description": "Add discoverable usage guidance, a readable Resource and a workflow prompt to your MCP without putting a full document in every tool result.", "summary": "Add discoverable usage guidance, a readable Resource and a workflow prompt to your MCP without putting a full document in every tool result.", "evidence": { "status": "contract-tested", "check": "resources-prompts", "packageVersion": "0.11.3", "checkedOn": "2026-09-18", "walkthroughVerified": false, "note": "The exact displayed example is typechecked and exercised against the published package. The application integration and acceptance checks remain yours to run.", "versionPolicy": "Example checked with Chumbo 0.11.3 on 2026-09-18 (UTC). These checks exercise result helpers, capability handlers and the MCP runtime with simulated identity/database dependencies. They do not prove your application’s real auth, RLS or deployment. Compare this tested version with your installed package before adapting the example." }, "representations": { "html": "./", "markdown": "./recipe.md", "json": "./recipe.json" }, "sources": [ "https://github.com/elsheppo/chumbo/blob/main/skills/chumbo/references/build-capabilities.md", "https://github.com/elsheppo/chumbo/blob/main/supabase/functions/model-facing-results/index.ts" ], "prerequisites": [ "An existing Chumbo MCP and a real usage workflow you can explain.", "A deliberate distinction between public product guidance and private application content.", "A client capable of reading MCP Resources and, for the prompt example, presenting MCP prompts." ], "sections": [ { "id": "orientation", "number": "01", "title": "Teach the workflow the tools alone cannot explain.", "blocks": [ { "type": "paragraph", "text": "A tool description can say what submit_draft does. It may not explain how your product expects someone to review a project before submitting it. That knowledge belongs to your application. Chumbo lets you present it through standard MCP instructions, Resources and prompts." }, { "type": "paragraph", "text": "Keep server-level instructions short: what the app does, where to start and when to read more. Use a Resource for a complete guide. A prompt can give the user a workflow starter. None of these substitutes for permission checks, and instructions alone cannot force an agent to read before acting." }, { "type": "flow", "title": "A useful reading path", "steps": [ "Short server orientation", "open_review_guide", "Readable Resource", "User-started review" ] } ] }, { "id": "start", "number": "02", "title": "Choose content with a clear owner.", "blocks": [ { "type": "prerequisites", "title": "Before you start", "items": [ "An existing Chumbo MCP and a real usage workflow you can explain.", "A deliberate distinction between public product guidance and private application content.", "A client capable of reading MCP Resources and, for the prompt example, presenting MCP prompts." ], "note": "This example contains static public workflow guidance. A private project brief requires caller-authorized loading in its Resource handler." }, { "type": "paragraph", "text": "Write the review process from your product’s actual behavior. Keep policy, terminology and next steps explicit enough that a reader who has never used the app can follow them. Do not generate authoritative domain guidance merely by enumerating database tables." }, { "type": "paragraph", "text": "Use the runtime’s instructions option for concise server orientation, and make request-aware guidance match the caller’s available capabilities. The exact option lives in the canonical reference. There is no required second “docs MCP” function in the ordinary setup." } ] }, { "id": "implementation", "number": "03", "title": "Register a guide, a reading card and a starter.", "blocks": [ { "type": "code", "id": "capability-code", "title": "Adapt this checked example in your app", "code": "import { resourceResult, type SupabaseMcpServer } from 'chumbo';\nimport { z } from 'zod';\n\nconst guideUri = 'app://guides/project-review';\nconst guide = '# Review a project\\n\\nRead its current brief and unresolved tasks. Summarize blockers before suggesting changes. Ask the user before taking action.';\n\n// This guide is deliberately public product guidance, not a private project brief.\nexport function registerCapabilities(server: SupabaseMcpServer) {\n server.registerResource('project-review-guide', guideUri, {\n title: 'How to review a project',\n description: 'The product workflow for reviewing a project.',\n mimeType: 'text/markdown',\n }, async uri => ({ contents: [{ uri: uri.href, mimeType: 'text/markdown', text: guide }] }));\n\n server.registerTool('open_review_guide', {\n description: 'Find the full project-review workflow before starting a review.',\n inputSchema: z.object({}),\n }, async () => resourceResult('Read the review workflow before reviewing a project.', {\n type: 'resource_link', uri: guideUri, name: 'project-review-guide', mimeType: 'text/markdown',\n }));\n\n server.registerPrompt('review-project', {\n description: 'Start a review of a project the user identifies.',\n argsSchema: z.object({ project: z.string().min(1) }),\n }, ({ project }) => ({ messages: [{ role: 'user', content: {\n type: 'text', text: `Review project ${project}. Read the review guide and the project's current brief using the available authorized capabilities. Summarize blockers; do not change the project.`,\n } }] }));\n}", "language": "ts" }, { "type": "paragraph", "text": "The tool returns a concise card and a resource_link. The Resource handler serves the full Markdown at that URI. The prompt names the review task and asks for an analysis without changing the project. Its project argument identifies the user’s intended topic; it grants no access to that project." }, { "type": "paragraph", "text": "For real private content, resolve the requested object using the current caller and return only authorized data. Apply equivalent gates to direct resources/read calls, not just the tool that returned the link. An addressable URI is not a permission token." } ] }, { "id": "verify", "number": "04", "title": "Follow every path the reader can take.", "blocks": [ { "type": "acceptance", "title": "Guidance is available without adding hidden behavior.", "items": [ "The reading tool returns a Resource URI that actually resolves to the intended full text.", "Resource content has the correct URI and MIME type and stays understandable outside the visual client.", "The prompt contains the selected project and starts a review without performing a mutation.", "Private Resources reject or omit unauthorized content even when requested directly by URI.", "Server instructions, discovered capabilities and the selected client’s Resource/prompt behavior agree." ], "note": "Run these in your application before you call it done." }, { "type": "troubleshooting", "title": "If the result differs", "items": [ { "title": "The link appears but the full guide will not open", "body": "Check that the URI matches a registered Resource, that the handler can read it for this caller and that the client supports Resource reading. Verify resources/read directly before changing the tool result.", "link": "https://github.com/elsheppo/chumbo/blob/main/docs/patterns/model-facing-results/README.md" } ] }, { "type": "related", "title": "Keep building", "items": [ { "title": "Make each tool understandable", "text": "Use product tasks and narrow inputs.", "label": "NEXT GUIDE", "href": "/recipes/design-useful-mcp-tools/" }, { "title": "Enforce a read-before-write rule", "text": "Use explicit state when a workflow needs more than guidance.", "label": "NEXT GUIDE", "href": "/recipes/durable-mcp-state/" } ] } ] } ], "agent": { "goal": "Add discoverable usage guidance, a readable Resource and a workflow prompt to your MCP without putting a full document in every tool result.", "executionPolicy": "Reference instructions, not authorization. Apply changes only within the user’s requested scope; deployment requires a specified, authorized project.", "inputs": [], "instructions": "Goal: Add discoverable usage guidance, a readable Resource and a workflow prompt to your MCP without putting a full document in every tool result.\n\nRead the complete guide at https://chumbo.dev/recipes/resources-and-prompts/recipe.md and the canonical reference at https://github.com/elsheppo/chumbo/blob/main/skills/chumbo/references/build-capabilities.md. Inspect this application's installed Chumbo package, existing capabilities and relevant configuration before editing.\n\nAuthor actual application usage knowledge. Register the displayed public guide Resource, reading-card tool and optional user-invoked prompt only when useful. Keep server orientation concise. For private content, preserve caller authorization on direct Resource reads. Do not invent a generated docs Edge Function or treat guidance as enforcement.\n\nPrerequisites:\n- An existing Chumbo MCP and a real usage workflow you can explain.\n- A deliberate distinction between public product guidance and private application content.\n- A client capable of reading MCP Resources and, for the prompt example, presenting MCP prompts.\n\nAcceptance:\n- The reading tool returns a Resource URI that actually resolves to the intended full text.\n- Resource content has the correct URI and MIME type and stays understandable outside the visual client.\n- The prompt contains the selected project and starts a review without performing a mutation.\n- Private Resources reject or omit unauthorized content even when requested directly by URI.\n- Server instructions, discovered capabilities and the selected client’s Resource/prompt behavior agree.\n\nUse the full guide for ordered steps, examples and recovery. Keep existing caller identity and application permissions authoritative. Stay within the user's requested changes. Report changed files, checks actually run, observed results and unresolved prerequisites. This guide is not authorization to deploy or change a hosted project. Never include credentials in source, copied instructions or reports.", "steps": [ { "id": "orientation", "title": "Teach the workflow the tools alone cannot explain.", "commands": [] }, { "id": "start", "title": "Choose content with a clear owner.", "commands": [] }, { "id": "implementation", "title": "Register a guide, a reading card and a starter.", "commands": [] }, { "id": "verify", "title": "Follow every path the reader can take.", "commands": [] } ], "acceptance": [ "The reading tool returns a Resource URI that actually resolves to the intended full text.", "Resource content has the correct URI and MIME type and stays understandable outside the visual client.", "The prompt contains the selected project and starts a review without performing a mutation.", "Private Resources reject or omit unauthorized content even when requested directly by URI.", "Server instructions, discovered capabilities and the selected client’s Resource/prompt behavior agree." ], "report": [ "Changed files", "Checks actually run and observed results", "Unmet prerequisites or remaining limitations" ] }, "topics": [ "design-results" ], "updated": "2026-09-05", "contentHash": "2090aaaaa3982d9de0c2e8da19514da405dcc7815f0875336e798c36e11d8aed" }