startgg-mcp: Instructions file for Codex

Agent Protocol

Server: startgg-mcp Version: 0.1.0 Framework: @cyanheads/mcp-ts-core

Read the framework docs first: node_modules/@cyanheads/mcp-ts-core/CLAUDE.md contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.

---

First Session

Remove this section from CLAUDE.md / AGENTS.md after completing these steps. The skills and conventions below remain — this block is one-time onboarding only.

1. Read the framework API — node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
2. Run the setup skill — read skills/setup/SKILL.md and follow its checklist (project orientation, agent protocol file selection, echo definition cleanup, skill sync)
3. Design the server — read skills/design-mcp-server/SKILL.md and work through it with the user to map the domain into tools, resources, and services before scaffolding

---

Core Rules

• Logic throws, framework catches. Tool/resource handlers are pure — throw on failure, no try/catch. Plain Error is fine; the framework catches, classifies, and formats. Use error factories (notFound(), validationError(), etc.) when the error code matters.
• Use ctx.log for request-scoped logging. No console calls.
• Use ctx.state for tenant-scoped storage. Never access persistence directly.
• Check ctx.elicit / ctx.sample for presence before calling.
• Secrets in env vars only — never hardcoded.

---

Patterns

Tool

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

export const searchItems = tool('search_items', {
  description: 'Search inventory items by query.',
  annotations: { readOnlyHint: true },
  input: z.object({
    query: z.string().describe('Search terms'),
    limit: z.number().default(10).describe('Max results'),
  }),
  output: z.object({
    items: z.array(z.object({
      id: z.string().describe('Item ID'),
      name: z.string().describe('Item name'),
    })).describe('Matching items'),
  }),
  auth: ['inventory:read'],

  async handler(input, ctx) {
    const items = await findItems(input.query, input.limit);
    ctx.log.info('Search completed', { query: input.query, count: items.length });
    return { items };
  },

  format: (result) => [{ type: 'text', text: `Found ${result.items.length} items` }],
});