mcp-rtfm

Instructions

Implementation Reference

• src/index.ts:1057-1090 (handler)

  The handler for the 'search_docs' tool in the CallToolRequestSchema switch statement. Extracts arguments, calls the searchDocContent helper function, formats results as JSON with cache metadata, and handles errors.

  case "search_docs": {
    const { projectPath, query } = request.params.arguments as {
      projectPath: string;
      query: string;
    };
  
    try {
      const results = await searchDocContent(projectPath, query);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              query,
              results,
              cache: {
                timestamp: state.contextCache.timestamp,
                ttl: CACHE_TTL,
                expires: state.contextCache.timestamp ?
                  new Date(state.contextCache.timestamp + CACHE_TTL).toISOString() :
                  null
              }
            }, null, 2)
          }
        ]
      };
    } catch (error: unknown) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      throw new McpError(
        ErrorCode.InternalError,
        `Error searching documentation: ${errorMessage}`
      );
    }
  }

• src/index.ts:515-528 (schema)

  Input schema definition for the search_docs tool, specifying projectPath and query parameters.

  inputSchema: {
    type: "object",
    properties: {
      projectPath: {
        type: "string",
        description: "Path to the project root directory"
      },
      query: {
        type: "string",
        description: "Search query to find in documentation"
      }
    },
    required: ["projectPath", "query"]
  }

• src/index.ts:512-529 (registration)

  Registration of the search_docs tool in the ListToolsRequestSchema handler, including name, description, and input schema.

  {
    name: "search_docs",
    description: "Search across documentation files with highlighted results",
    inputSchema: {
      type: "object",
      properties: {
        projectPath: {
          type: "string",
          description: "Path to the project root directory"
        },
        query: {
          type: "string",
          description: "Search query to find in documentation"
        }
      },
      required: ["projectPath", "query"]
    }
  },

• src/index.ts:321-373 (helper)

  Helper function implementing the core search logic: caches queries, performs regex search on lines of each doc file in .handoff_docs/, collects highlighted matches per file.

  const searchDocContent = async (projectPath: string, query: string): Promise<SearchResult[]> => {
    // Check cache first
    if (
      state.contextCache.lastQuery === query &&
      state.contextCache.results &&
      state.contextCache.timestamp &&
      Date.now() - state.contextCache.timestamp < CACHE_TTL
    ) {
      return state.contextCache.results;
    }
  
    const results: SearchResult[] = [];
    const docsPath = `${projectPath}/.handoff_docs`;
    const searchRegex = new RegExp(query, 'gi');
  
    for (const doc of DEFAULT_DOCS) {
      try {
        const content = await fs.readFile(`${docsPath}/${doc}`, 'utf8');
        const lines = content.split('\n');
        const matches = lines
          .map((line, index) => {
            const match = searchRegex.exec(line);
            if (match) {
              return {
                line,
                lineNumber: index + 1,
                highlight: {
                  start: match.index,
                  end: match.index + match[0].length
                }
              };
            }
            return null;
          })
          .filter((match): match is NonNullable<typeof match> => match !== null);
  
        if (matches.length > 0) {
          results.push({ file: doc, matches });
        }
      } catch (error) {
        console.error(`Error searching ${doc}:`, error);
      }
    }
  
    // Update cache
    state.contextCache = {
      lastQuery: query,
      results,
      timestamp: Date.now()
    };
  
    return results;
  };

• src/index.ts:50-60 (schema)

  Type definition for SearchResult, structuring the output of search results with file and per-line match highlights.

  interface SearchResult {
    file: string;
    matches: Array<{
      line: string;
      lineNumber: number;
      highlight: {
        start: number;
        end: number;
      };
    }>;
  }