Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Computer Index find files containing 'quarterly report'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A personal file-indexing system for /home/Declan/. It builds a SQLite/libSQL
database that catalogs every file with filesystem metadata, extracts text
content, chunks it, and generates vector embeddings for semantic search.
The pipeline runs in phases. Every script is standalone, re-runnable, and reads
its settings from config.toml.
scour → extract → chunk → dedup → embed → fts
(metadata) (text) (splits) (dupes) (vectors) (keyword idx)An MCP server (serve.py) exposes the finished index — semantic search, keyword
search, and file lookup — to agents and the MCP Inspector.
Python 3.14, managed by uv
ollama with the embedding model pulled (Phase 2, Step 3 only)
NVIDIA GPU (RTX 4060, 8 GB VRAM) for embeddings and PDF OCR
Related MCP server: File AI
uv sync # create the venv and install dependencies
ollama pull qwen3-embedding:4b # embedding model (~2.5 GB), for embed.pyAll paths and exclusions live in config.toml:
root_path — directory to index (default /home/Declan)
db_path — database file (default computer_index.db)
exclude_dirs.names / exclude_dirs.paths — directories the scour skips
schema.sql is the DDL reference for the four core tables (scour_runs,
files, file_contents, text_chunks) plus the file_fts keyword index.
scour.py walks root_path with os.scandir, skips excluded/inaccessible
directories, and records one metadata row per file into files. No file
contents are read here.
uv run scour.py # scan config root_path into computer_index.db
uv run scour.py --root /some/project # scan a different directory (testing)
uv run scour.py --db /tmp/test.db # write to a throwaway db (testing)Prints a validation summary (counts by extension, depth, largest files).
report.py generates a self-contained report.html dashboard (Plotly) from the
latest scour run — treemap of disk usage, extension/depth/age breakdowns,
largest files.
uv run report.py # writes report.html
uv run report.py --db /tmp/test.db # report on a different dbextract.py)Reads eligible files from the latest scour run and writes text into
file_contents. Three tiers:
Tier 1 — direct read: code, document, and config files read as UTF-8.
Data files are skipped as data_file (kept out of the search index): JSON
always, and CSV/TSV/PSV when the content looks tabular.
Tier 2 — PDFs: Unlimited-OCR to structured markdown (needs the separate
GPU OCR stack: uv sync --extra ocr, ollama stopped so the OCR model fits VRAM).
Tier 3 — structured docs: .docx (python-docx), .ipynb (nbformat).
uv run extract.py # all implemented tiers
uv run extract.py --tier 1 # direct-read files only
uv run extract.py --tier 3 # structured docs only
uv run extract.py --dry-run # show what would be extracted
uv run extract.py --reextract # re-extract files that already have a rowPrints extraction coverage by extension and files skipped by reason.
chunk.py)Splits file_contents text into text_chunks. Prose/markdown is split
structurally (headers → paragraphs → sentences → words, ~4000-char target with
400-char overlap); code and config files are stored whole (truncated at 128K
chars).
uv run chunk.py # chunk everything not yet chunked
uv run chunk.py --stats # print chunk stats, no processing
uv run chunk.py --rechunk # delete all chunks and redo
uv run chunk.py --file-id 12345 # chunk one file (testing)Prints total chunks, per-file averages, token distribution, and sample chunks.
dedup.py)Collapses identical-content files so only one copy is embedded and searched. For
each group of files sharing a content_hash, the shallowest path (min depth,
then lowest file_id) is kept and the others' chunks are deleted. Non-destructive
to disk, files, and file_contents; idempotent.
uv run dedup.py # remove duplicate-content chunks
uv run dedup.py --dry-run # show what would be removedcleanup_data.py is a related one-off: it applies the current data-file rule
(extract.is_data_file) to already-indexed files, deleting their chunks and
reclassifying them as data_file.
embed.py)Generates a qwen3-embedding:4b vector (2560 dims) for each chunk via ollama,
using libsql for the vector column. Requires the ollama server running:
ollama serve # in a separate terminaluv run embed.py # embed all chunks with a NULL embedding
uv run embed.py --stats # embedding coverage
uv run embed.py --search "reinforcement learning policy gradient"embed.py migrates the database to libsql and adds the embedding /
embedding_model columns on first run. Switching models (dimension change)
recreates the embedding column, so re-run embed.py to re-embed.
The 4B embedder (~2.5 GB) and the Phase-2 PDF OCR model (~6 GB) do not both fit in 8 GB VRAM — stop ollama before running OCR.
fts.py)Builds file_fts, an external-content FTS5 mirror of text_chunks.chunk_text,
for the MCP server's keyword search. Indexing chunks (not whole files) keeps
keyword search aligned with semantic search — deduped and data-file content has
no chunks, so it stays out of both. Rebuilt in one pass (no triggers) — re-run
after any stage that changes text_chunks (chunk / dedup / cleanup).
uv run fts.py # (re)build the keyword index
uv run fts.py --status # indexed row count, no changesserve.py)A FastMCP stdio server that exposes the finished index to agents. Four read-only tools:
tool | backend | use for |
| vector cosine ( | meaning-based / conceptual queries |
| FTS5 + BM25 ( | exact terms, names, literal phrases |
|
| read a whole file, or a chunk window around a hit |
|
| browse by extension / name |
search and search_keyword return a file_id and a chunk index per hit;
pass both to get_file_content(file_id, around_chunk=…) to expand around a
specific chunk instead of dumping a whole document. Semantic queries are embedded
with the qwen3 query instruction (query-side only — no document re-embed).
uv add "mcp[cli]" # one-time: install the MCP SDK + Inspector
uv run mcp dev serve.py # interactive Inspector (browser UI)
uv run serve.py # run over stdio for an agent hostsearch needs the ollama server running (it embeds the query); the other tools
do not. Point an agent host at it with a stdio entry running uv run serve.py
from the project directory.
Four tables (schema.sql):
table | populated by | holds |
| scour | one row per scan (root, timing, counts, status) |
| scour | filesystem metadata, one row per path |
| extract | extracted text or skip reason, one row per file |
| chunk / embed | text chunks + embedding vectors |
| fts | FTS5 keyword index over chunk text |
Phase 1 (scour): complete
Phase 2: extraction (Tier 1/2/3) · chunking · dedup · embeddings (4B) — complete
Phase 3 (Basic MCP server / agent access): search / search_keyword / get_file_content / list_files over stdio — complete
Read an indexed file's text by file_id (from a search result).
Two modes:
around_chunk < 0 (default): the whole extracted text. Large files are capped — prefer a window (below) to read a specific part of a big doc.
around_chunk >= 0: that chunk plus radius chunks on each side, in order.
This is how you expand around a specific search hit: pass the file_id and
the chunk index the search returned to get its surrounding context.
| Name | Required | Description | Default |
|---|---|---|---|
| radius | No | ||
| file_id | Yes | ||
| around_chunk | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It discloses that large files are capped and explains the behavior of the two modes in detail. It does not mention auth requirements or error handling, but provides enough behavioral context for typical usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two short paragraphs and bullet points for clarity. Every sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (so return values need not be detailed), the description covers purpose, all parameters, usage modes, and a behavioral caveat about capping. It is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must add meaning for all parameters. It thoroughly explains 'around_chunk' (negative vs. non-negative behavior), 'radius' (number of surrounding chunks), and 'file_id' (from search result). This adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads an indexed file's text by file_id from a search result. It uses specific verbs ('read') and resource ('file's text'), and distinguishes from sibling tools that search or list files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains two modes (whole text vs. chunk expansion) and when to use each, including a recommendation to prefer window mode for large files. It also mentions passing the chunk index from search results. However, it does not explicitly state when not to use this tool or provide direct comparisons with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse indexed files by metadata (not a content search).
Filter by extension (e.g. "pdf", no leading dot) and/or name_contains (a substring matched anywhere in the full path — a filename or a folder). Use for exploration like "my PDFs under Documents" or "notebooks named train". Returns file_id, size, and path, largest first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| extension | No | ||
| name_contains | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states behavior: returns file_id, size, path, largest first; explains name_contains matches anywhere in full path. Lacks auth, rate limits, but for a read-only listing, these are less critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is one paragraph but well-structured: purpose, filter explanation, use cases, return info. Could be slightly more concise, but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is simple (3 params, output schema exists), the description covers the key aspects: purpose, filters, return fields, ordering. It is complete enough for an agent to understand and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must explain parameters. It explains extension (no leading dot) and name_contains (substring anywhere in path). The limit parameter is not explained, but its default and type are in schema. Description adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's for browsing indexed files by metadata, not content search. It distinguishes from content search and gives specific filter examples (extension, name_contains). Verb 'Browse' and resource 'indexed files' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description says 'Use for exploration like...' and explicitly states 'not a content search', implying when to use this tool vs sibling tools like search. However, it does not explicitly name alternatives or say when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic (meaning-based) search across all indexed files.
Use for conceptual questions where the exact wording is unknown, e.g. "my notes on value functions" or "that paper about cousin marriage". For an exact term, function name, or literal phrase, use search_keyword instead. Returns ranked chunks with file path, file_id, and cosine distance (lower = closer). Requires the ollama server to be running.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 mentions the output format and a requirement, but does not explicitly state that the tool is read-only, nor does it disclose any potential side effects, rate limits, or costs. The description is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences covering purpose, use cases, sibling tool distinction, return format, and a prerequisite. No wasted words, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 parameters and an output schema (reducing need to explain returns), the description covers purpose, usage, and a constraint. However, it lacks explanation for the limit parameter and does not elaborate on the output schema or error conditions. Still, it is fairly complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify parameters. Only the query parameter is implied by the semantic search context; the limit parameter is not explained at all (default 5, but no indication of its effect on results).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is for semantic search across indexed files, contrasting with search_keyword. It specifies the return format (ranked chunks with file path, file_id, cosine distance).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises use for conceptual questions where exact wording is unknown, and directs to use search_keyword for exact terms. Also notes a prerequisite (ollama server must be running).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Exact keyword / phrase search over extracted file text (FTS5, BM25-ranked).
Use when looking for a specific term, function name, or literal phrase rather than a conceptual match — semantic search is weak at exact matches. Supports FTS5 syntax: AND / OR / NOT, "quoted phrases", and prefix* wildcards. For meaning-based questions use search instead. Returns files with a matching snippet and file_id, best matches first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| keyword | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes supported FTS5 syntax, return format (files with snippet and file_id, ordered by relevance). No annotations provided, so description carries full burden; it is sufficiently transparent for a read-only 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: one sentence for purpose, one for usage guidance, one for syntax, and one for return format. Every sentence adds value without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, output schema exists), the description covers purpose, usage, supported syntax, and return format. It distinguishes from siblings and is complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but description adds context that keyword supports FTS5 syntax. However, it does not explain the 'limit' parameter or provide details on parameter semantics beyond the overall purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is for exact keyword/phrase search over extracted file text, specifies the use of FTS5 and BM25 ranking, and distinguishes it from the sibling tool 'search' which is for semantic search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (looking for specific term, function name, literal phrase) and when not to (meaning-based questions, recommending 'search' instead). Provides clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_file_contentlist_filessearchsearch_keywordEach tool targets a distinct operation: semantic search, keyword search, content retrieval, and file browsing. Their descriptions clearly differentiate use cases, reducing ambiguity.
All tool names follow a consistent snake_case verb_noun pattern (search, search_keyword, get_file_content, list_files), making it predictable.
4 tools is appropriate for a file index server, covering search, retrieval, and browsing without unnecessary bloat or missing core functionality.
The set covers search (semantic and keyword) and file content access, but lacks a tool for indexing or updating files. However, for a query-only server this is acceptable.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Agentic search over your Dewey document collections from any MCP-compatible client.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
The Needle MCP server enables semantic search on documents stored in files like PDFs, DOCX, and XLSX by connecting AI applications to external data sources. It provides capabilities to create and manage document collections, perform natural language searches on stored content, and retrieve relevant information without requiring exact keyword matches.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/DeclanFinerty/mcp-pc-index'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
