RAGmonsters Custom PostgreSQL MCP Server

Instructions

Implementation Reference

• src/mcp-server/tools/monsters.js:132-289 (handler)

  The core handler function for the getMonsterById tool. It queries the database for monster details by ID, retrieves associated abilities, keywords, flaws, strengths, and weaknesses, formats them into a structured JSON response, and returns it in the expected MCP content format.

  export async function getMonsterById(params) {
    try {
      if (!dbPool) {
        throw new Error('Database pool not initialized. Call initialize() first.');
      }
      
      logger.info(`getMonsterById called with params: ${JSON.stringify(params)}`);
      
      const { monsterId } = params;
      
      if (!monsterId) {
        logger.error('Monster ID is required but was not provided');
        throw new Error('Monster ID is required');
      }
      
      logger.debug(`Fetching monster with ID: ${monsterId}`);
      // Get basic monster information
      const monsterQuery = `
        SELECT 
          m.*
        FROM 
          monsters m
        WHERE 
          m.monster_id = $1
      `;
      
      const monsters = await executeQuery(dbPool, monsterQuery, [monsterId]);
      
      if (monsters.length === 0) {
        throw new Error(`Monster with ID ${monsterId} not found`);
      }
      
      const monster = monsters[0];
      
      // Get monster's abilities and keywords
      const abilitiesQuery = `
        SELECT 
          k.keyword_name,
          k.rating,
          a.ability_name,
          a.mastery_value
        FROM 
          questworlds_stats qs
        JOIN 
          keywords k ON qs.stats_id = k.stats_id
        JOIN 
          abilities a ON k.keyword_id = a.keyword_id
        WHERE 
          qs.monster_id = $1
        ORDER BY 
          k.keyword_name, a.ability_name
      `;
      
      const abilities = await executeQuery(dbPool, abilitiesQuery, [monsterId]);
      
      // Get monster's flaws
      const flawsQuery = `
        SELECT 
          f.flaw_name,
          f.rating
        FROM 
          questworlds_stats qs
        JOIN 
          flaws f ON qs.stats_id = f.stats_id
        WHERE 
          qs.monster_id = $1
        ORDER BY 
          f.rating DESC
      `;
      
      const flaws = await executeQuery(dbPool, flawsQuery, [monsterId]);
      
      // Get monster's strengths (augments)
      const strengthsQuery = `
        SELECT 
          target_name,
          modifier
        FROM 
          augments
        WHERE 
          monster_id = $1
      `;
      
      const strengths = await executeQuery(dbPool, strengthsQuery, [monsterId]);
      
      // Get monster's weaknesses (hindrances)
      const weaknessesQuery = `
        SELECT 
          target_name,
          modifier
        FROM 
          hindrances
        WHERE 
          monster_id = $1
      `;
      
      const weaknesses = await executeQuery(dbPool, weaknessesQuery, [monsterId]);
      
      // Organize abilities by keyword
      const keywordAbilities = {};
      abilities.forEach(item => {
        if (!keywordAbilities[item.keyword_name]) {
          keywordAbilities[item.keyword_name] = {
            name: item.keyword_name,
            rating: item.rating,
            abilities: []
          };
        }
        
        keywordAbilities[item.keyword_name].abilities.push({
          name: item.ability_name,
          mastery: item.mastery_value
        });
      });
      
      // Format the response
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            id: monster.monster_id,
            name: monster.name,
            category: monster.category,
            habitat: monster.habitat,
            rarity: monster.rarity,
            discovery: monster.discovery,
            physicalAttributes: {
              height: monster.height,
              weight: monster.weight,
              appearance: monster.appearance
            },
            powers: {
              primary: monster.primary_power,
              secondary: monster.secondary_power,
              special: monster.special_ability
            },
            keywords: Object.values(keywordAbilities),
            flaws: flaws.map(flaw => ({
              name: flaw.flaw_name,
              rating: flaw.rating
            })),
            strengths: strengths.map(strength => ({
              target: strength.target_name,
              modifier: strength.modifier
            })),
            weaknesses: weaknesses.map(weakness => ({
              target: weakness.target_name,
              modifier: weakness.modifier
            }))
          })
        }]
      };
    } catch (error) {
      logger.error(`Error in getMonsterById: ${error.message}`);
      logger.error(error.stack);
      throw new Error(`Failed to retrieve monster details: ${error.message}`);
    }
  }

• src/mcp-server/tools/index.js:38-45 (registration)

  The registration of the getMonsterById tool with the MCP server using server.addTool(). Includes the tool name, description, input schema using Zod (requiring a numeric monsterId), and binds the execute function to the imported getMonsterById handler.

  server.addTool({
    name: 'getMonsterById',
    description: 'Get detailed information about a specific monster by ID',
    parameters: z.object({
      monsterId: z.number().describe('ID of the monster to retrieve')
    }),
    execute: getMonsterById
  });

• src/mcp-server/tools/index.js:41-43 (schema)

  Zod schema definition for the getMonsterById tool input parameters, specifying that monsterId must be a number.

  parameters: z.object({
    monsterId: z.number().describe('ID of the monster to retrieve')
  }),