search_documents
Search indexed documents by keyword or phrase. Returns results ranked by TF-IDF relevance with scores and excerpts.
Instructions
Search indexed documents by keyword or phrase using TF-IDF ranking. Returns up to max_results results, each with a relevance score and excerpt.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| max_results | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- server/main.py:39-56 (handler)The @mcp.tool() decorated function that implements the search_documents tool. It delegates to DocumentIndex.search() and formats results into a string.
@mcp.tool() def search_documents(query: str, max_results: int = 5) -> str: """ Search indexed documents by keyword or phrase using TF-IDF ranking. Returns up to max_results results, each with a relevance score and excerpt. """ results = _index.search(query, max_results=max_results) if not results: return f"No documents matched '{query}'. Try different keywords or use list_documents." lines = [f"Found {len(results)} result(s) for '{query}':\n"] for i, r in enumerate(results, 1): lines.append(f"{i}. **{r['filename']}** (score: {r['score']})") lines.append(f" {r['snippet']}") lines.append("") return "\n".join(lines) - server/main.py:39-40 (registration)The @mcp.tool() decorator registers search_documents as an MCP tool.
@mcp.tool() def search_documents(query: str, max_results: int = 5) -> str: - server/main.py:40-40 (schema)Input schema for search_documents: query (str, required) and max_results (int, default 5).
def search_documents(query: str, max_results: int = 5) -> str: - server/search.py:92-112 (helper)The DocumentIndex.search() method that performs TF-IDF ranking and returns results with filename, score, and snippet.
def search(self, query: str, max_results: int = 5) -> list[dict[str, Any]]: query_terms = [t for t in tokenize(query) if t not in STOP_WORDS] if not query_terms: return [] scored = [ (name, self._score(name, query_terms)) for name in self.documents ] scored.sort(key=lambda x: x[1], reverse=True) results = [] for filename, score in scored[:max_results]: if score <= 0: break results.append({ "filename": filename, "score": round(score, 4), "snippet": self._snippet(self.documents[filename], query_terms), }) return results