CodeGuard MCP Server

Instructions

Implementation Reference

• src/handlers/tools.ts:87-117 (handler)

  The main handler function for get_security_instructions tool. It accepts args (language, context, filepath), calls matchInstructions to find applicable security rules, formats results as markdown, and returns them in MCP tool response format with content array.

  function getSecurityInstructions(
    args: Record<string, unknown>,
    instructions: Instruction[]
  ) {
    const language = args.language as string | undefined;
    const context = args.context as string | undefined;
    const filepath = args.filepath as string | undefined;
    
    // Match instructions
    const result = matchInstructions(
      { language, context, filepath },
      instructions
    );
    
    // Format as markdown
    const content = result.instructions
      .map(i => {
        return `## ${i.frontmatter.description}\n\n${i.content}`;
      })
      .join('\n\n---\n\n');
    
    return {
      content: [
        {
          type: 'text',
          text: content || 'No specific security instructions matched. Follow general security best practices.',
        },
      ],
      isError: false,
    };
  }

• src/handlers/tools.ts:11-55 (registration)

  Tool registration in listTools function. Defines the get_security_instructions tool with its name, description, and inputSchema (language, context, filepath properties). Also includes the callTool routing function that dispatches to the handler.

  export function listTools() {
    return {
      tools: [
        {
          name: 'get_security_instructions',
          description: 'Get security instructions for code generation. Returns applicable security rules based on language, context, or file path.',
          inputSchema: {
            type: 'object',
            properties: {
              language: {
                type: 'string',
                description: 'Programming language (python, javascript, typescript, java, c, etc.)',
              },
              context: {
                type: 'string',
                description: 'Context keywords (auth, crypto, database, api, password, hash, etc.)',
              },
              filepath: {
                type: 'string',
                description: 'File path for pattern matching (e.g., src/auth/login.ts)',
              },
            },
          },
        },
        {
          name: 'validate_code_security',
          description: 'Validate code snippet against security rules and return applicable instructions',
          inputSchema: {
            type: 'object',
            properties: {
              code: {
                type: 'string',
                description: 'Code snippet to validate',
              },
              language: {
                type: 'string',
                description: 'Programming language of the code',
              },
            },
            required: ['code', 'language'],
          },
        },
      ],
    };
  }

• src/rules/matcher.ts:170-218 (helper)

  Core matchInstructions helper function that implements the matching logic. Scores instructions based on filepath patterns, language extensions, and context keywords, then sorts by priority and returns the top 15 matched instructions with metadata.

  export function matchInstructions(
    context: MatchContext,
    allInstructions: Instruction[]
  ): MatchResult {
    const scoredInstructions: ScoredInstruction[] = [];
    const matchedBy: MatchResult['metadata']['matchedBy'] = {};
    
    // Score all instructions
    for (const instruction of allInstructions) {
      const scored = scoreInstruction(instruction, context);
      if (scored.score > 0) {
        scoredInstructions.push(scored);
      }
    }
    
    // Sort by priority (high to low), then by score
    scoredInstructions.sort((a, b) => {
      if (a.priority !== b.priority) {
        return b.priority - a.priority;
      }
      return b.score - a.score;
    });
    
    // Count matches by type
    matchedBy.critical = scoredInstructions.filter(s => s.priority === Priority.CRITICAL).length;
    matchedBy.language = scoredInstructions.filter(s => s.matchReasons.includes('language')).length;
    matchedBy.filepath = scoredInstructions.filter(s => s.matchReasons.includes('filepath')).length;
    matchedBy.context = scoredInstructions.filter(s => s.matchReasons.includes('context')).length;
    
    // Priority breakdown
    const priorityBreakdown = {
      critical: scoredInstructions.filter(s => s.priority === Priority.CRITICAL).length,
      high: scoredInstructions.filter(s => s.priority === Priority.HIGH).length,
      medium: scoredInstructions.filter(s => s.priority === Priority.MEDIUM).length,
      low: scoredInstructions.filter(s => s.priority === Priority.LOW).length,
    };
    
    // Limit to top 15 rules to keep response size manageable
    const topInstructions = scoredInstructions.slice(0, 15);
    
    return {
      instructions: topInstructions.map(s => s.instruction),
      metadata: {
        totalMatched: scoredInstructions.length,
        matchedBy,
        priorityBreakdown,
      },
    };
  }

• src/handlers/prompts.ts:64-97 (handler)

  Alternative handler for the same functionality in the prompts API. Returns the security instructions formatted as a prompt message with description and user role content, used for MCP prompt-based interactions.

  function getSecurityInstructions(args: Record<string, string>, instructions: Instruction[]) {
    const { language, context, filepath } = args;
    
    // Match instructions
    const result = matchInstructions(
      { language, context, filepath },
      instructions
    );
    
    // Format matched instructions
    const content = result.instructions
      .map(i => `# ${i.frontmatter.description}\n\n${i.content}`)
      .join('\n\n---\n\n');
    
    // Build context description
    const parts = [];
    if (language) parts.push(`language: ${language}`);
    if (context) parts.push(`context: ${context}`);
    if (filepath) parts.push(`file: ${filepath}`);
    const contextDesc = parts.length > 0 ? ` (${parts.join(', ')})` : '';
    
    return {
      description: `Security instructions for code generation${contextDesc}`,
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: content || 'No specific instructions matched. Follow general security best practices.',
          },
        },
      ],
    };
  }