Skip to main content
Glama
DaniloBlancoMotta

FastMCP Documentation Search Server

by DaniloBlancoMotta
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

FastMCP Search Server 🚀

Português | English

Português

Servidor baseado no protocolo MCP (Model Context Protocol) projetado para fornecer uma infraestrutura de Arquitetura de Acesso + Contexto. Este sistema permite que Agentes de IA estendam suas capacidades através de ferramentas locais e recuperação de dados especializados sem a necessidade de processamento de LLM no lado do servidor.

🏗️ Arquitetura e Funcionamento

O sistema opera como uma camada intermediária de inteligência local, automatizando a busca e o processamento de dados para injetar apenas o necessário na janela de contexto do cliente.

graph TD
    User((Usuário)) --> Client[MCP Client / Interface]
    
    subgraph "Camada de Comunicação"
        Client <==> Protocol(MCP Protocol)
    end
    
    subgraph "FastMCP Server (Infraestrutura Local)"
        Protocol <==> Tools{Motor de Ferramentas}
        Tools --> Index[minsearch / TF-IDF]
        Tools --> Scraping[Jina Reader]
        Tools --> Logic[Lógica Local]
    end
    
    Index --- Docs[(Documentação Local)]
    Scraping --- Web((Web))

🛠️ Ferramentas, Inputs e Outputs

Ferramenta

Descrição

Input

Output

search_docs

Busca semântica inteligente usando TF-IDF.

query (string)

Lista dos 5 documentos mais relevantes com preview.

scrape_page

Web scraping otimizado para IA.

url (string)

Conteúdo da página em Markdown limpo.

hash_text

Geração de hash para integridade.

text (string)

String SHA-256 hexadecimal.

add

Operação aritmética precisa.

a (int), b (int)

Soma literal dos números.

💻 Stack Tecnológica

  • FastMCP: Framework principal para orquestração do protocolo.

  • minsearch: Motor de busca minimalista para indexação in-memory.

  • Scikit-learn & Pandas: Vetorização e manipulação de dados estruturados.

  • Jina Reader API: Conversão de HTML para Markdown legível por IA.

🚀 Instalação

# Clone o repositório e instale as dependências
uv sync

# Execute o servidor
uv run python main.py

Related MCP server: Documentation Fetcher & RAG Search

English

A server based on the Model Context Protocol (MCP) designed to provide an Architecture of Access + Context. This system allows AI Agents to extend their capabilities through local tools and specialized data retrieval without the need for LLM processing on the server side.

🏗️ Architecture and Workflow

The system operates as an intermediate layer of local intelligence, automating data search and processing to inject only what is necessary into the client's context window.

graph TD
    User((User)) --> Client[MCP Client / Interface]
    
    subgraph "Communication Layer"
        Client <==> Protocol(MCP Protocol)
    end
    
    subgraph "FastMCP Server (Local Infrastructure)"
        Protocol <==> Tools{Tools Engine}
        Tools --> Index[minsearch / TF-IDF]
        Tools --> Scraping[Jina Reader]
        Tools --> Logic[Local Logic]
    end
    
    Index --- Docs[(Local Docs)]
    Scraping --- Web((Web))

🛠️ Tools, Inputs, and Outputs

Tool

Description

Input

Output

search_docs

Intelligent semantic search using TF-IDF.

query (string)

List of the 5 most relevant docs with content preview.

scrape_page

AI-optimized web scraping.

url (string)

Page content in clean Markdown.

hash_text

Hash generation for data integrity.

text (string)

SHA-256 hexadecimal string.

add

Precise arithmetic operation.

a (int), b (int)

Literal sum of the numbers.

💻 Technical Stack

  • FastMCP: Core framework for protocol orchestration.

  • minsearch: Minimalist search engine for in-memory indexing.

  • Scikit-learn & Pandas: Vectorization and structured data handling.

  • Jina Reader API: HTML to AI-readable Markdown conversion.

🚀 Getting Started

# Clone the repository and install dependencies
uv sync

# Run the server
uv run python main.py

📝 Conclusão / Conclusion

Este projeto demonstra a viabilidade de construir camadas de suporte para agentes de IA que priorizam a eficiência e a soberania dos dados. Ao utilizar o protocolo MCP, removemos a fricção entre bases de dados locais e modelos globais, garantindo que o contexto injetado seja preciso, relevante e processado de forma otimizada.

This project demonstrates the feasibility of building support layers for AI agents that prioritize efficiency and data sovereignty. By using the MCP protocol, we remove the friction between local databases and global models, ensuring that the injected context is accurate, relevant, and optimally processed.

Developed as part of the AI Dev Bootcamp.

Available Tools

4 tools
addA

Add two numbers

ParametersJSON Schema
NameRequiredDescriptionDefault
aYes
bYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral burden. 'Add two numbers' accurately and sufficiently communicates a pure arithmetic operation, with no indication of side effects or hidden behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four words long, contains zero filler, and conveys the complete operation. It is front-loaded and every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-integer addition tool with an output schema and no siblings, this description is nearly complete. It could mention the return value or pure behavior explicitly, but the output schema and inherent simplicity reduce that need.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It clarifies that both parameters are numbers to be added, but it does not name them or describe each parameter individually. Since addition is commutative, the lack of role differentiation is a minor gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise verb ('add') and a clear resource ('two numbers'), making the tool's purpose immediately obvious. With no sibling tools, there is no ambiguity to resolve.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is clear: this tool is for summing two numbers. It does not explicitly discuss when not to use it, but with no sibling tools and only two integer parameters, the context is straightforward.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hash_textB

Hash a string using SHA-256

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the action ('hash a string') but lacks behavioral details: it doesn't specify if the operation is deterministic, reversible, or idempotent; mention performance or rate limits; describe error handling (e.g., for empty strings); or explain the output format. For a tool with no annotations, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—a single sentence with no wasted words. It's front-loaded with the core action ('hash a string') and includes essential detail (SHA-256). Every part earns its place, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (one parameter, no nested objects) and the presence of an output schema (which handles return values), the description is somewhat complete. However, with no annotations and minimal parameter guidance, it lacks context on behavior, usage, and constraints. It's adequate for basic understanding but has clear gaps in guiding effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds minimal meaning beyond the input schema. It implies the 'text' parameter is the string to be hashed, but with 0% schema description coverage, the schema only defines 'text' as a string without context. The description doesn't elaborate on constraints (e.g., length limits, encoding) or provide examples. Since there's only one parameter, the baseline is 4, but the lack of added semantic detail reduces it to 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('hash') and resource ('a string'), specifying the algorithm (SHA-256). It distinguishes from siblings like 'add', 'scrape_page', and 'search_docs' by focusing on cryptographic hashing rather than arithmetic, web scraping, or document search. However, it doesn't explicitly differentiate from potential sibling hashing tools (e.g., 'hash_text_md5'), so it's not a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention use cases (e.g., data integrity checks, password hashing), prerequisites, or comparisons to other tools. With siblings like 'add' and 'search_docs', there's no explicit context for choosing 'hash_text' over them, leaving usage unclear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

scrape_pageB

Scrape the content of a web page using Jina reader

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the scraping action and method ('Jina reader'), but fails to disclose critical traits like rate limits, authentication needs, error handling, or what content is extracted (e.g., text, HTML). This leaves significant gaps in understanding the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It is appropriately sized and front-loaded, with zero waste, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (web scraping with one parameter) and the presence of an output schema (which handles return values), the description is minimally adequate. However, with no annotations and low schema coverage, it lacks details on behavioral aspects and parameter usage, leaving room for improvement in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It implies the 'url' parameter is for specifying the web page to scrape, but adds no details beyond what the schema name suggests (e.g., format, validation, or examples). With only one parameter, the baseline is higher, but the description provides minimal additional meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('scrape') and resource ('content of a web page'), specifying the method ('using Jina reader'). It distinguishes from siblings like 'add', 'hash_text', and 'search_docs' by focusing on web scraping, but doesn't explicitly contrast with them. The purpose is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, such as other scraping methods or tools for similar tasks. It lacks context about prerequisites, limitations, or typical use cases, leaving the agent without explicit usage instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_docsB

Search FastMCP documentation for a query

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions searching but doesn't describe what kind of results to expect, whether there are rate limits, authentication requirements, or how results are returned. The description is minimal and lacks important behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that communicates the core function without unnecessary words. It's appropriately sized for a simple search tool and front-loads the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (which handles return values) and only one simple parameter, the description is reasonably complete for basic understanding. However, it lacks important contextual details about search behavior, result format, or limitations that would be helpful for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It mentions the 'query' parameter but doesn't explain what constitutes a valid query, search syntax, or examples. The description adds minimal semantic value beyond what's implied by the parameter name, meeting the baseline for this coverage level.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search') and target resource ('FastMCP documentation'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools (which are unrelated to documentation search), so it doesn't reach the highest score of 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or context for usage. It simply states what the tool does without indicating appropriate scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updates
    • First observedadd
    • First observedhash_text
    • First observedscrape_page
    • First observedsearch_docs
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: add performs arithmetic, hash_text handles cryptographic hashing, scrape_page extracts web content, and search_docs searches documentation. The functions are so different that misselection is highly unlikely.

Naming Consistency2/5

The naming is inconsistent with mixed conventions: add uses a simple verb, hash_text uses verb_noun, scrape_page uses verb_noun, and search_docs uses verb_noun. There is no uniform pattern, and the single-word 'add' deviates significantly from the others.

Tool Count3/5

With 4 tools, the count is borderline for the server's stated purpose of 'Documentation Search Server'—only one tool directly supports this, while others are unrelated utilities. This feels thin and misaligned with the domain, though not extreme.

Completeness2/5

For a documentation search server, there is a significant gap: only search_docs directly serves the purpose, while add, hash_text, and scrape_page are unrelated. This lacks coverage for typical documentation workflows like browsing, filtering, or managing documentation, likely causing agent failures.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers