add-resource

Context

Resources use the resource() builder from @cyanheads/mcp-ts-core. Each resource lives in src/mcp-server/resources/definitions/ with a .resource.ts suffix. The standard registration pattern uses a definitions/index.ts barrel that collects all resources into an allResourceDefinitions array for createApp(). Fresh scaffolds start with direct imports in src/index.ts — the barrel is introduced as definitions grow. Match the pattern already used by the project you're editing.

Tool coverage. Not all MCP clients expose resources — many are tool-only (Claude Code, Cursor, most chat UIs). Before adding a resource, verify the same data is reachable via the tool surface — either through a dedicated tool, included in another tool's output, or bundled into a broader tool. A resource whose data has no tool path is invisible to a large share of agents.

Steps

1. Gather the resource's URI template, purpose, and data shape from the user's request — ask only if genuinely absent
2. Design the URI — use {paramName} for path parameters (e.g., myscheme://{itemId}/data)
3. Create the file at src/mcp-server/resources/definitions/{{resource-name}}.resource.ts
4. Register the resource in the project's existing createApp() resource list (directly in src/index.ts for fresh scaffolds, or via a barrel if the repo already has one)
5. Run bun run devcheck to verify
6. Smoke-test with bun run rebuild && bun run start:stdio < /dev/null (or start:http) — the Core services constructed log record must list the new resource in its resources field (the message text shows only counts); if it doesn't, the resource never reached createApp()

Template

/**
 * @fileoverview {{RESOURCE_DESCRIPTION}}
 * @module mcp-server/resources/definitions/{{RESOURCE_NAME}}
 */

import { resource, z } from '@cyanheads/mcp-ts-core';

export const {{RESOURCE_EXPORT}} = resource('{{scheme}}://{{{paramName}}}/data', {
  description: '{{RESOURCE_DESCRIPTION}}',
  mimeType: 'application/json',
  // size: 1024,  // optional: content size in bytes, if known
  params: z.object({
    {{paramName}}: z.string().describe('{{PARAM_DESCRIPTION}}'),
  }),
  // auth: ['resource:{{resource_name}}:read'],

  async handler(params, ctx) {
    ctx.log.debug('Fetching resource', { {{paramName}}: params.{{paramName}} });
    // Pure logic — throw on failure, no try/catch
    return { /* resource data */ };
  },

  list: async (extra) => ({
    resources: [
      {
        uri: '{{scheme}}://all',
        name: '{{RESOURCE_LIST_NAME}}',
        mimeType: 'application/json',
      },
    ],
  }),
});