Skip to main content
Glama
msharsha565-create

docsearch-mcp

by msharsha565-create
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

docsearch-mcp

Local document search with cited sources, as an MCP server and a web app. It uses BM25 ranking implemented in pure Python: no API key, no model download, no vector database.

demo

Why

Agents need grounded context they can cite. This gives any MCP client two tools, search_docs and list_sources, over your own folder of .md/.txt/.rst files, with the source and a relevance score returned for every chunk so answers can be traced back.

Related MCP server: local-knowledge-search

Run the demo

pip install -e ".[dev]"
docsearch-web                      # http://127.0.0.1:8000

The default corpus is the docstrings of ~70 Python standard-library modules (about 1,000 chunks), so it works with nothing to configure. Try "run subprocess and capture output" or "compute sha256 hash".

Search your own documents instead:

DOCSEARCH_DIR=./my-docs docsearch-web

Use it from an MCP client

{ "mcpServers": { "docsearch": { "command": "docsearch-mcp-server",
                                  "env": { "DOCSEARCH_DIR": "/path/to/docs" } } } }

Tool

Returns

search_docs(query, k=5)

Top-k chunks: source, chunk, score, text

list_sources()

Number of chunks and the list of source documents

How it works

Documents are split into ~120-word chunks on paragraph boundaries. Chunks are tokenized (lowercased, stopwords removed; the source name is indexed too) and ranked with Okapi BM25 (k1=1.5, b=0.75).

Tests

python -m pytest        # 10 tests
ruff check src tests

Limitations

  • Lexical matching only: a query must share words with the text. It does not understand synonyms the way embedding search can.

  • The index is rebuilt in memory at startup, which suits small and medium corpora.

  • Plain-text formats only (no PDF or HTML parsing).

Available Tools

2 tools
list_sourcesC

Number of indexed chunks and the list of source documents.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.8/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 behavioral burden, yet it only restates return content (chunk count and source list). It says nothing about ordering, completeness of the listing, size of the result set, or that the operation is a read-only enumeration.

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

Conciseness3/5

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

It is a single short sentence with no padding, but it is a sentence fragment that leads with output content rather than a verb and resource. Brevity here comes at the cost of a clear opening statement of action.

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?

For a zero-parameter read tool with an output schema already documenting return values, the bar is low and the description is just barely sufficient. It still fails to state the action or route the agent away from search_docs.

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

Parameters4/5

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description does not misleadingly imply any inputs.

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

Purpose3/5

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

The description names the resource (source documents) and mentions the chunk count, but it is a noun-phrase fragment with no verb, so it describes the return payload rather than stating the action. It also doesn't distinguish itself from the sibling search_docs, which an agent could easily confuse with a listing operation.

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?

There is no statement of when to use this tool versus search_docs, and no mention that it takes no filters. The agent must infer that this is a browse/enumerate operation and that search_docs is the filtered alternative.

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

search_docsA

Search the indexed documents with BM25. Returns the top k chunks with their source, relevance score and text, so answers can cite the source.

ParametersJSON Schema
NameRequiredDescriptionDefault
kNo
queryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations, the description carries the burden and does disclose the ranking method (BM25) and the returned fields (source, relevance score, text). It omits permissions, limits, empty-result behavior, and other operational constraints, which is a moderate gap for a search tool.

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?

Two compact sentences, front-loaded with the core action and followed by return behavior. Every sentence adds useful information without repetition.

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-parameter search tool with an output schema, the description covers purpose, mechanism, and result shape well. The main missing piece is explicit routing against list_sources and fuller parameter constraints.

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 k controls the number of top chunks returned and that query is the search input, but gives no default, range, or query syntax details.

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?

States a specific verb and resource: search indexed documents using BM25. This clearly distinguishes it in spirit from list_sources, though it does not explicitly name or contrast with that sibling.

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

Usage Guidelines3/5

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

The phrase 'so answers can cite the source' implies the retrieval use case, but the description does not say when to use search_docs versus list_sources or any other alternative. Usage is inferable but not guided.

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. 2 tool updatesv0.1.0
    • First observedlist_sources
    • 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.3/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one searches content by relevance, the other enumerates indexed sources. There is no realistic way to confuse a BM25 search with listing sources.

Naming Consistency5/5

Both names follow the same verb_noun snake_case pattern (search_docs, list_sources). The convention is predictable and readable.

Tool Count3/5

Two tools is thin for a search server; useful capabilities like fetching a full document or filtering search by source are absent. Still, the count is not absurd for a narrowly scoped read-only index.

Completeness3/5

Core retrieval and source enumeration are covered, but there is no way to retrieve a whole document, filter searches by source, or manage the index. Agents hitting a chunk boundary or needing document-level context will dead-end.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • RAG In A Box MCP Server

    DevNexsler
    F
    license
    Not graded
    quality
    B
    maintenance
    Enables any MCP-compatible AI assistant to search, filter, and retrieve information from a local document collection using a hybrid search pipeline with vector, BM25, reranking, and LLM enrichment.
    4
    -

  • local-knowledge-search

    komplettsystem
    F
    license
    Not graded
    quality
    B
    maintenance
    Enables fast local hybrid search over a folder of markdown files via MCP, combining BM25 and vector similarity with explicit relevance verdicts and no LLM or network calls at query time.
    1
    -

  • docs-search-mcp

    JuanMiguelAbellan
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI clients to search and read a folder of Markdown/text documents via a read-only MCP server with hybrid BM25 and local embedding search, treating the calling model as untrusted.
    11 npm
    MIT

  • Sunstone Weave: Local Semantic

    space-bacon
    A
    license
    A
    quality
    A
    maintenance
    Semantic code search for any MCP client: indexes local folders of code and docs and answers plain-language or code queries with matching passages, file paths, line ranges and scores. Embedding runs on the local CPU with the Motherlode code-search encoder, so no file content leaves the machine; the encoder downloads once from Hugging Face. Install: npx -y blackwindow-weave-mcp.
    6
    4
    30 npm
    Business Source 1.1