CoderSwap MCP Server

Instructions

Implementation Reference

• src/index.ts:486-565 (registration)

  Full registration of the 'coderswap_search' MCP tool, including schema definitions and handler function.

  server.registerTool(
    'coderswap_search',
    {
      title: 'CoderSwap Hybrid Search',
      description: 'Execute a hybrid search query against a CoderSwap project using DSL-powered ranking',
      inputSchema: {
        project_id: z.string().min(1, 'project_id is required'),
        query: z.string().min(1, 'query is required'),
        top_k: z.number().min(1).max(50).default(10),
        snippet_length: z.number().min(50).max(1000).default(200)
      },
      outputSchema: {
        query: z.string(),
        result_count: z.number(),
        results: z.array(z.object({
          score: z.number(),
          title: z.string().optional(),
          snippet: z.string().optional()
        }))
      }
    },
    async ({ project_id, query, top_k = 10, snippet_length = 200 }) => {
      try {
        log('debug', 'Executing search', { project_id, query, top_k })
        const result = await client.search({ project_id, query, top_k, snippet_length })
  
        const output = {
          query,
          result_count: result.results.length,
          results: result.results.slice(0, top_k).map(r => ({
            score: r.score,
            title: r.title,
            snippet: r.snippet
          }))
        }
  
        if (result.results.length === 0) {
          return {
            content: [{
              type: 'text',
              text: `No results found for: "${query}"`
            }],
            structuredContent: output
          }
        }
  
        // Format results with rich detail
        const formattedResults = result.results
          .slice(0, top_k)
          .map((r, i) => {
            const medal = i === 0 ? '🥇' : i === 1 ? '🥈' : i === 2 ? '🥉' : `${i + 1}.`
            const score = ((r.score ?? 0) * 100).toFixed(1)
            let text = `${medal} Score: ${score}%`
            if (r.title) text += `\n   ${r.title}`
            if (r.snippet) text += `\n   ${r.snippet.substring(0, 150)}...`
            return text
          })
          .join('\n\n')
  
        log('info', `Search returned ${result.results.length} results`)
  
        return {
          content: [{
            type: 'text',
            text: `Found ${result.results.length} result(s) for: "${query}"\n\n${formattedResults}`
          }],
          structuredContent: output
        }
      } catch (error) {
        log('error', 'Search failed', { project_id, query, error: error instanceof Error ? error.message : error })
        return {
          content: [{
            type: 'text',
            text: `✗ Search failed: ${error instanceof Error ? error.message : 'Unknown error'}`
          }],
          isError: true
        }
      }
    }
  )

• src/index.ts:507-564 (handler)

  The core handler function for the coderswap_search tool. It invokes the CoderSwapClient.search method, processes and formats the results with scores and medals, and returns structured content.

  async ({ project_id, query, top_k = 10, snippet_length = 200 }) => {
    try {
      log('debug', 'Executing search', { project_id, query, top_k })
      const result = await client.search({ project_id, query, top_k, snippet_length })
  
      const output = {
        query,
        result_count: result.results.length,
        results: result.results.slice(0, top_k).map(r => ({
          score: r.score,
          title: r.title,
          snippet: r.snippet
        }))
      }
  
      if (result.results.length === 0) {
        return {
          content: [{
            type: 'text',
            text: `No results found for: "${query}"`
          }],
          structuredContent: output
        }
      }
  
      // Format results with rich detail
      const formattedResults = result.results
        .slice(0, top_k)
        .map((r, i) => {
          const medal = i === 0 ? '🥇' : i === 1 ? '🥈' : i === 2 ? '🥉' : `${i + 1}.`
          const score = ((r.score ?? 0) * 100).toFixed(1)
          let text = `${medal} Score: ${score}%`
          if (r.title) text += `\n   ${r.title}`
          if (r.snippet) text += `\n   ${r.snippet.substring(0, 150)}...`
          return text
        })
        .join('\n\n')
  
      log('info', `Search returned ${result.results.length} results`)
  
      return {
        content: [{
          type: 'text',
          text: `Found ${result.results.length} result(s) for: "${query}"\n\n${formattedResults}`
        }],
        structuredContent: output
      }
    } catch (error) {
      log('error', 'Search failed', { project_id, query, error: error instanceof Error ? error.message : error })
      return {
        content: [{
          type: 'text',
          text: `✗ Search failed: ${error instanceof Error ? error.message : 'Unknown error'}`
        }],
        isError: true
      }
    }
  }

• src/coderswap-client.ts:133-147 (helper)

  Implementation of the search method in CoderSwapClient class, which makes the HTTP POST request to the /v1/search API endpoint.

  async search(input: SearchInput) {
    const res = await fetch(`${this.baseUrl}/v1/search`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({
        project_id: input.project_id,
        query: input.query,
        snippet_length: input.snippet_length ?? 200,
        settings: {
          k: input.top_k ?? 5
        }
      })
    })
    return this.handleResponse<{ results: SearchResult[]; request_id?: string }>(res)
  }

• src/types.ts:17-22 (schema)

  Zod schema definition for SearchInput type used by the CoderSwapClient.search method.

  export const searchSchema = z.object({
    project_id: z.string().min(1, 'project_id is required'),
    query: z.string().min(1, 'query is required'),
    top_k: z.number().min(1).max(50).optional(),
    snippet_length: z.number().min(50).max(1000).optional()
  })