Better Email MCP

Instructions

Implementation Reference

• src/tools/registry.ts:259-279 (handler)

  Handler for the 'help' tool that validates the tool name, reads the corresponding documentation file, and returns the tool name and documentation content

  case 'help': {
    const toolName = (args as { tool_name: string }).tool_name
    if (!isValidToolName(toolName)) {
      throw new EmailMCPError(
        `Invalid tool name: ${toolName}`,
        'VALIDATION_ERROR',
        'Valid: messages, folders, attachments, send, help'
      )
    }
    const resource = RESOURCES.find((r) => r.uri === `email://docs/${toolName}`)
    if (!resource) {
      throw new EmailMCPError(`Documentation not found for: ${toolName}`, 'DOC_NOT_FOUND', 'Check tool_name')
    }
    try {
      const content = await readFile(join(DOCS_DIR, resource.file), 'utf-8')
      result = { tool: toolName, documentation: content }
    } catch {
      throw new EmailMCPError(`Documentation not found for: ${toolName}`, 'DOC_NOT_FOUND', 'Check tool_name')
    }
    break
  }

• src/tools/registry.ts:169-190 (schema)

  Schema definition for the 'help' tool including name, description, annotations, and inputSchema with tool_name parameter

  {
    name: 'help',
    description: 'Get full documentation for a tool. Use when compressed descriptions are insufficient.',
    annotations: {
      title: 'Help',
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false
    },
    inputSchema: {
      type: 'object',
      properties: {
        tool_name: {
          type: 'string',
          enum: ['messages', 'folders', 'attachments', 'send', 'help'],
          description: 'Tool to get documentation for'
        }
      },
      required: ['tool_name']
    }
  }

• src/tools/registry.ts:196-311 (registration)

  Registration function that sets up all tools including 'help' with the MCP server via CallToolRequestSchema handler

  export function registerTools(server: Server, accounts: AccountConfig[]) {
    server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools: TOOLS
    }))
  
    // Resources handlers for full documentation
    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
      resources: RESOURCES.map((r) => ({
        uri: r.uri,
        name: r.name,
        mimeType: 'text/markdown'
      }))
    }))
  
    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
      const { uri } = request.params
      const resource = RESOURCES.find((r) => r.uri === uri)
  
      if (!resource) {
        throw new EmailMCPError(
          `Resource not found: ${uri}`,
          'RESOURCE_NOT_FOUND',
          `Available: ${RESOURCES.map((r) => r.uri).join(', ')}`
        )
      }
  
      const content = await readFile(join(DOCS_DIR, resource.file), 'utf-8')
      return {
        contents: [{ uri, mimeType: 'text/markdown', text: content }]
      }
    })
  
    server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const { name, arguments: args } = request.params
  
      if (!args) {
        return {
          content: [
            {
              type: 'text',
              text: 'Error: No arguments provided'
            }
          ],
          isError: true
        }
      }
  
      try {
        let result
  
        switch (name) {
          case 'messages':
            result = await messages(accounts, args as unknown as MessagesInput)
            break
          case 'folders':
            result = await folders(accounts, args as unknown as FoldersInput)
            break
          case 'attachments':
            result = await attachments(accounts, args as unknown as AttachmentsInput)
            break
          case 'send':
            result = await send(accounts, args as unknown as SendInput)
            break
          case 'help': {
            const toolName = (args as { tool_name: string }).tool_name
            if (!isValidToolName(toolName)) {
              throw new EmailMCPError(
                `Invalid tool name: ${toolName}`,
                'VALIDATION_ERROR',
                'Valid: messages, folders, attachments, send, help'
              )
            }
            const resource = RESOURCES.find((r) => r.uri === `email://docs/${toolName}`)
            if (!resource) {
              throw new EmailMCPError(`Documentation not found for: ${toolName}`, 'DOC_NOT_FOUND', 'Check tool_name')
            }
            try {
              const content = await readFile(join(DOCS_DIR, resource.file), 'utf-8')
              result = { tool: toolName, documentation: content }
            } catch {
              throw new EmailMCPError(`Documentation not found for: ${toolName}`, 'DOC_NOT_FOUND', 'Check tool_name')
            }
            break
          }
          default:
            throw new EmailMCPError(
              `Unknown tool: ${name}`,
              'UNKNOWN_TOOL',
              `Available tools: ${TOOLS.map((t) => t.name).join(', ')}`
            )
        }
  
        const jsonText = JSON.stringify(result, null, 2)
        return {
          content: [
            {
              type: 'text',
              text: wrapToolResult(name, jsonText)
            }
          ]
        }
      } catch (error) {
        const enhancedError = error instanceof EmailMCPError ? error : enhanceError(error)
  
        return {
          content: [
            {
              type: 'text',
              text: aiReadableMessage(enhancedError)
            }
          ],
          isError: true
        }
      }
    })
  }

• src/tools/helpers/security.ts:57-60 (helper)

  isValidToolName validation function used by 'help' tool to prevent path traversal attacks by checking against valid tool names

  /** Validate tool name for help documentation requests */
  export function isValidToolName(name: string): boolean {
    return VALID_TOOL_NAMES.has(name)
  }