The MCP Pattern: Giving AI Tools It Can Actually Use

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'

const server = new McpServer({
  name: 'pep-tools',
  version: '1.0.0',
})

// Tool: get-prompt-by-id
// Follows the verb-noun naming convention
server.tool(
  'get-prompt-by-id',
  // Description acts as a prompt for the model
  'Retrieves a specific prompt template by its unique identifier. ' +
  'Use this when the user references a prompt by name or ID, or ' +
  'when you need to inspect a prompt before suggesting modifications. ' +
  'Returns the full prompt text, metadata, and version history.',
  {
    // Parameter schema using Zod (validated automatically)
    promptId: z.string()
      .describe('The unique identifier of the prompt (e.g., "sys-codereview-v3")'),
    includeHistory: z.boolean()
      .default(false)
      .describe('Whether to include previous versions of this prompt'),
  },
  async ({ promptId, includeHistory }) => {
    const prompt = await db.prompts.findById(promptId)

    if (!prompt) {
      return {
        content: [{
          type: 'text' as const,
          text: `No prompt found with ID "${promptId}". ` +
                `Use list-prompts to see available prompt IDs.`,
        }],
        isError: true,
      }
    }

    const result: Record<string, unknown> = {
      id: prompt.id,
      name: prompt.name,
      version: prompt.version,
      text: prompt.text,
      lastModified: prompt.updatedAt,
    }

    if (includeHistory) {
      result.history = await db.promptVersions.findByPromptId(promptId)
    }

    return {
      content: [{
        type: 'text' as const,
        text: JSON.stringify(result, null, 2),
      }],
    }
  }
)

// GOOD: Typed, constrained, documented parameters
server.tool(
  'search-prompt-library',
  'Searches the prompt library by keyword, tag, or category. ' +
  'Returns matching prompts sorted by relevance. ' +
  'Use this when the user asks to find prompts or browse the library.',
  {
    query: z.string()
      .min(2)
      .max(200)
      .describe('Search query: keywords, prompt name, or natural language description'),
    category: z.enum(['system', 'user', 'few-shot', 'chain-of-thought'])
      .optional()
      .describe('Filter results to a specific prompt category'),
    limit: z.number()
      .int()
      .min(1)
      .max(50)
      .default(10)
      .describe('Maximum number of results to return'),
    sortBy: z.enum(['relevance', 'date', 'name'])
      .default('relevance')
      .describe('How to sort results'),
  },
  async ({ query, category, limit, sortBy }) => {
    // Parameters arrive validated and typed
    // No need for manual type checking or sanitization
    const results = await promptLibrary.search({
      query,
      category,
      limit,
      sortBy,
    })

    return {
      content: [{
        type: 'text' as const,
        text: JSON.stringify({
          total: results.total,
          returned: results.items.length,
          items: results.items,
        }, null, 2),
      }],
    }
  }
)

// Error handling pattern for MCP tools
server.tool(
  'update-prompt-version',
  'Creates a new version of an existing prompt. Use this when the user ' +
  'wants to modify a prompt and preserve its version history.',
  {
    promptId: z.string().describe('The prompt to update'),
    newText: z.string().min(1).describe('The updated prompt text'),
    changeNote: z.string().optional().describe('Description of what changed and why'),
  },
  async ({ promptId, newText, changeNote }) => {
    try {
      const existing = await db.prompts.findById(promptId)

      if (!existing) {
        return {
          content: [{
            type: 'text' as const,
            text: `Error: Prompt "${promptId}" does not exist. ` +
                  `To see available prompts, use the list-prompts tool. ` +
                  `To create a new prompt, use create-prompt instead.`,
          }],
          isError: true,
        }
      }

      if (newText === existing.text) {
        return {
          content: [{
            type: 'text' as const,
            text: `No changes detected. The new text is identical to version ` +
                  `${existing.version} of "${promptId}". If you intended to make ` +
                  `changes, please verify the new text differs from the current version.`,
          }],
          isError: true,
        }
      }

      const updated = await db.prompts.createVersion({
        promptId,
        text: newText,
        changeNote: changeNote || 'No change note provided',
        previousVersion: existing.version,
      })

      return {
        content: [{
          type: 'text' as const,
          text: JSON.stringify({
            success: true,
            promptId,
            previousVersion: existing.version,
            newVersion: updated.version,
            changeNote: updated.changeNote,
          }, null, 2),
        }],
      }
    } catch (error) {
      return {
        content: [{
          type: 'text' as const,
          text: `Failed to update prompt "${promptId}": ${error instanceof Error ? error.message : 'Unknown error'}. ` +
                `This may be a temporary issue. You can retry this operation, ` +
                `or use get-prompt-by-id to verify the current state of the prompt.`,
        }],
        isError: true,
      }
    }
  }
)