RAGmonsters Custom PostgreSQL MCP Server

Instructions

Implementation Reference

• src/mcp-server/tools/monsters.js:415-493 (handler)

  The handler function that implements the getMonsterByName tool. It queries the database for monsters whose names partially match the provided name (case-insensitive), returns up to 5 results with basic details, or a not-found message.

  export async function getMonsterByName(params) {
    try {
      if (!dbPool) {
        throw new Error('Database pool not initialized. Call initialize() first.');
      }
      
      logger.info(`getMonsterByName called with params: ${JSON.stringify(params)}`);
      
      const { name } = params;
      
      if (!name) {
        throw new Error('Monster name is required');
      }
      
      // Simple partial match query (case insensitive)
      const query = `
        SELECT 
          m.monster_id,
          m.name,
          m.category,
          m.habitat,
          m.rarity,
          m.primary_power,
          m.secondary_power,
          m.special_ability
        FROM 
          monsters m
        WHERE 
          LOWER(m.name) LIKE LOWER($1)
        ORDER BY
          m.name ASC
        LIMIT 5
      `;
      
      const monsters = await executeQuery(dbPool, query, [`%${name}%`]);
      
      if (monsters.length === 0) {
        logger.info(`No monsters found with name: ${name}`);
        return {
          content: [{
            type: 'text',
            text: JSON.stringify({
              found: false,
              message: `No monsters found with name: ${name}`
            })
          }]
        };
      }
      
      // Format the response for the matches
      logger.info(`Found ${monsters.length} monsters matching name: ${name}`);
      
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            found: true,
            count: monsters.length,
            monsters: monsters.map(monster => ({
              id: monster.monster_id,
              name: monster.name,
              category: monster.category,
              habitat: monster.habitat,
              rarity: monster.rarity,
              powers: {
                primary: monster.primary_power,
                secondary: monster.secondary_power,
                special: monster.special_ability
              }
            }))
          })
        }]
      };
    } catch (error) {
      logger.error(`Error in getMonsterByName: ${error.message}`);
      logger.error(error.stack);
      throw new Error(`Failed to retrieve monster by name: ${error.message}`);
    }
  }

• src/mcp-server/tools/index.js:64-71 (registration)

  Registers the getMonsterByName tool with the MCP server via server.addTool, defining its name, description, input schema using Zod, and binds the execute function imported from monsters.js.

  server.addTool({
    name: 'getMonsterByName',
    description: 'Get monsters by name (partial match, returns up to 5 matches)',
    parameters: z.object({
      name: z.string().describe('Name of the monster to search for (can be partial)')
    }),
    execute: getMonsterByName
  });

• src/mcp-server/tools/index.js:67-69 (schema)

  Zod schema definition for the input parameters of getMonsterByName: requires a 'name' string.

  parameters: z.object({
    name: z.string().describe('Name of the monster to search for (can be partial)')
  }),