Stacks Clarity MCP Server

Instructions

Implementation Reference

• src/utils/index.ts:194-206 (handler)

  Core handler function that implements the SIP search logic: iterates through all available SIPs, fetches each one's content, and returns SIP numbers matching the query.

  export const searchSIPs = async (query: string): Promise<string[]> => {
    const sips = getAvailableSIPs();
    const results: string[] = [];
    
    for (const sipNum of sips) {
      const content = await getSIPContent(sipNum);
      if (content.toLowerCase().includes(query.toLowerCase())) {
        results.push(sipNum);
      }
    }
    
    return results;
  };

• src/server.ts:98-115 (registration)

  Registers the 'search_sips' MCP tool, including name, description, Zod input schema, and execute handler that calls the searchSIPs function and formats results.

  server.addTool({
    name: "search_sips",
    description: "Search through all SIPs for content matching a specific query. Useful for finding standards related to specific topics.",
    parameters: z.object({
      query: z.string().describe("Search query (e.g., 'fungible token', 'NFT', 'metadata', 'cost analysis')"),
    }),
    execute: async (args) => {
      const results = await searchSIPs(args.query);
      if (results.length === 0) {
        return { text: `No SIPs found matching '${args.query}'`, type: "text" };
      }
      const resultList = results.map(num => `- SIP-${num.padStart(3, "0")}`).join("\n");
      return { 
        text: `SIPs matching '${args.query}':\n${resultList}\n\nUse get_sip with the SIP number to retrieve full content.`, 
        type: "text" 
      };
    },
  });

• src/server.ts:101-103 (schema)

  Zod schema defining the input parameter 'query' as a string for the search_sips tool.

  parameters: z.object({
    query: z.string().describe("Search query (e.g., 'fungible token', 'NFT', 'metadata', 'cost analysis')"),
  }),

• src/utils/index.ts:153-189 (helper)

  Helper function getSIPContent used by searchSIPs to fetch the full content of a SIP (markdown docs and Clarity code) for search matching.

  export const getSIPContent = async (sipNumber: string): Promise<string> => {
    try {
      const sipDir = pathJoin(stacksClarityStandardsDir, `sip-${sipNumber.padStart(3, "0")}`);
      
      if (!fs.existsSync(sipDir)) {
        return `SIP-${sipNumber} directory not found`;
      }
      
      const files = fs.readdirSync(sipDir);
      const mdFiles = files.filter((file) => file.endsWith(".md"));
      const clarFiles = files.filter((file) => file.endsWith(".clar"));
      
      if (mdFiles.length === 0 && clarFiles.length === 0) {
        return `No documentation or Clarity files found for SIP-${sipNumber}`;
      }
      
      let content = `# SIP-${sipNumber.padStart(3, "0")}\n\n`;
      
      // Read markdown documentation first
      for (const file of mdFiles) {
        const filePath = pathJoin(sipDir, file);
        const fileContent = await readFile(filePath, "utf-8");
        content += `## ${file}\n\n${fileContent}\n\n---\n\n`;
      }
      
      // Read Clarity contract files
      for (const file of clarFiles) {
        const filePath = pathJoin(sipDir, file);
        const fileContent = await readFile(filePath, "utf-8");
        content += `## Clarity Contract: ${file}\n\n\`\`\`clarity\n${fileContent}\n\`\`\`\n\n---\n\n`;
      }
      
      return content;
    } catch (error) {
      return `Error reading SIP-${sipNumber}: ${error}`;
    }
  };