Provides tools for semantic search and grounded Q&A over Zerodha's broker API documentation (Kite Connect), including ingesting new documents and retrieving answers with citations.
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., "@findocs-mcp What is the margin requirement for intraday trading on Kite Connect?"
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.
An eval-first, reliability-first MCP server for semantic search and grounded Q&A over a financial-docs corpus — Postgres + pgvector for retrieval, a first-class eval-loop that fails CI on regression.
FinDocs MCP gives an AI agent three tools over MCP: search a corpus of broker API documentation (Zerodha Kite Connect + Finvasia Shoonya), ask grounded questions that come back with citations, and ingest new documents. The interesting part isn't the RAG — it's the evaluation harness: every change is scored on retrieval recall, ranking quality, answer faithfulness, and refusal correctness, and a regression below baseline turns the build red.
This is the "tick-data validation, zero production mis-fires" discipline from quant trading infrastructure, applied to AI tooling: a confident wrong answer is worse than an honest "not found."
📚 Learning the codebase? The source is written as a reverse-learning layer: read it top-down from
src/mcp/server.ts(where an agent calls in) and follow the▼ LEARNcomment blocks down through retrieval, embeddings, cosine/pgvector, chunking, the refusal gate, and the eval-loop — to the linear algebra at the bottom. Each concept is taught inline, right where it's implemented.
┌─────────────────────────────────────────────┐
MCP client │ MCP server (stdio) │
(Claude Code/ │ search_docs · answer_question · ingest_doc│
Desktop) ─────▶│ │
└───────┬───────────────┬───────────────┬─────┘
│ │ │
┌──────▼─────┐ ┌─────▼──────┐ ┌─────▼──────┐
│ Embedder │ │ Retrieval │ │ Ingest │
│ (local │ │ + QA gate │ │ chunk→embed│
│ MiniLM) │ │ + citations│ │ →upsert │
└──────┬─────┘ └─────┬──────┘ └─────┬──────┘
└───────────────┼────────────────┘
┌──────▼───────┐
│ Postgres + │
│ pgvector │ HNSW cosine
└──────────────┘
evals/ ──▶ runner ──▶ metrics (recall@k · MRR · faithfulness · refusal)
│
▼
baseline.json gate ──▶ CI pass/failEverything is provider-agnostic behind thin adapters:
Concern | Default (zero cost, no secrets) | Swap-in |
Embeddings |
| OpenAI / Voyage |
LLM | deterministic heuristic (extractive + overlap judge) | local Ollama, or Anthropic / OpenAI |
Store | Postgres + pgvector (HNSW, cosine) | — |
The defaults run with no API keys and no per-call cost, which is exactly what makes the eval gate reproducible in CI.
Related MCP server: Modular RAG System
Tool | Description |
| Top-k chunks with cosine similarity scores + source metadata. |
| Retrieves, applies a confidence gate, synthesizes a grounded answer with citations, or refuses with "not found" when retrieval confidence is low. |
| Chunk → embed → upsert. Idempotent on content. |
answer_question never synthesizes when retrieval confidence is below the
configured floor. It refuses instead. The eval set includes out-of-corpus
negative cases specifically to prove this behavior holds (see
src/qa/gate.ts). With the default thresholds there is a clean
margin between in-corpus questions (top cosine ≥ 0.35) and out-of-corpus questions
(top cosine ≤ 0.31).
A labeled dataset of ~50 cases (evals/dataset.jsonl) —
question → expected supporting document(s), including negative/out-of-corpus cases.
Metrics (evals/harness/metrics.ts):
Metric | Question it answers |
recall@k | Did the right document make it into the top-k? |
MRR | How highly was the right document ranked? |
faithfulness | Is the answer actually supported by the retrieved chunks? (LLM-as-judge; deterministic fallback) |
refusal accuracy | Does it answer in-corpus questions and refuse out-of-corpus ones? |
Runner — pnpm eval prints a scorecard, writes
evals/results/{timestamp}.json, and appends a row to evals/history.ndjson so
you can track the score-over-time curve.
Regression gate — pnpm eval:gate compares the scorecard against
evals/baseline.json and exits non-zero if any metric drops
below threshold (minus a small epsilon). CI runs this on every PR.
Current baseline (calibrated against the real corpus):
recall@5 0.92 · MRR 0.80 · faithfulness 0.80 · refusal accuracy 0.90Offline smoke test:
pnpm calibrateruns the entire scoring pipeline with the real embedder against an in-memory index — no database required — useful for tuning thresholds and sanity-checking retrieval quality locally.
Prerequisites: Node 20+, pnpm (corepack enable pnpm), and
Docker (for the pgvector container).
pnpm install
cp .env.example .env # defaults match docker-compose
pnpm db:up # start Postgres + pgvector (host port 5433)
pnpm db:wait # wait until it accepts connections
pnpm migrate # apply schema + HNSW index
pnpm ingest # chunk → embed → upsert the corpus
pnpm eval # print the scorecard
pnpm eval:gate # run the regression gate (CI uses this)
pnpm dev # run the MCP server over stdioThe first
pnpm ingest/pnpm evaldownloads the MiniLM model (~90 MB) and caches it under.models/.
Build first (pnpm build), then point your MCP client at dist/mcp/server.js.
Claude Desktop — add to claude_desktop_config.json:
{
"mcpServers": {
"findocs": {
"command": "node",
"args": ["/absolute/path/to/findocs-mcp/dist/mcp/server.js"],
"env": {
"DATABASE_URL": "postgres://findocs:findocs@localhost:5433/findocs"
}
}
}
}Claude Code — register the server from the repo root:
claude mcp add findocs \
--env DATABASE_URL=postgres://findocs:findocs@localhost:5433/findocs \
-- node ./dist/mcp/server.jsThen ask things like "Search the docs for how GTT OCO orders work" or "How is the Kite Connect access token checksum computed?" — and try an out-of-corpus question to watch it refuse.
Demo recording goes here — replace with an asciinema cast or GIF:
# record: asciinema rec demo.cast -c "pnpm eval && pnpm dev"
src/
config.ts zod-validated env
db/ postgres.js client + repo (upsert / vectorSearch / getChunk)
embeddings/ Embedder interface + local transformers.js impl + factory
llm/ LLMProvider {synthesize, judge}: heuristic + ollama
ingest/ chunk · load · pipeline
retrieval/search.ts search_docs core
qa/ confidence gate + grounded answer with citations
mcp/server.ts MCP stdio server (3 tools, zod schemas)
evals/
dataset.jsonl labeled cases (incl. negatives)
harness/ metrics · runner · scorecard · gate (first-class module)
baseline.json regression thresholds
corpus/ vendored broker API docs (deterministic eval base)
db/ schema.sql · migrate · wait
scripts/calibrate.ts offline eval (no DB) for threshold tuningCorpus is a curated, vendored subset of public broker API documentation for demo and reproducibility; it may lag the official docs. Treat it as a fixture, not a source of truth for live trading.
TypeScript strict throughout (exactOptionalPropertyTypes, noUncheckedIndexedAccess,
…), ESM, no any in core paths. Tests in vitest.
Out of scope for v1: rerankers, hybrid BM25+vector, auth, web UI — the adapters are structured so these slot in without a rewrite.
MIT — see LICENSE.
Retrieves relevant chunks, synthesizes a grounded answer with citations, and refuses with "not found" when retrieval confidence is below the configured floor.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | Question to answer from the corpus |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It reveals a key behavior: refusal when retrieval confidence is low. However, it does not mention other potential behaviors like rate limits or permission requirements.
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 one sentence to convey the core functionality and a key behavior. It is front-loaded but could be better structured with separate sentences for different aspects.
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 (one parameter, no output schema), the description covers the main aspects: retrieval, synthesis, citations, and refusal. It lacks details on the output format or citation style, but it is reasonably complete.
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 input schema already fully describes the single required parameter 'question' (type, minLength, description). The description does not add additional semantic meaning to the parameter beyond what the schema provides.
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 specifies the action ('answers'), the resource ('question with citations'), and how it works ('retrieves relevant chunks, synthesizes a grounded answer with citations'). It also alludes to a behavior that distinguishes it from siblings like ingest_doc and search_docs.
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 implies usage for answering questions from a corpus, but does not explicitly state when to use this tool versus the sibling tools (search_docs for searching, ingest_doc for ingestion). No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Chunk → embed → upsert a document into pgvector. Provide either a URL to fetch or raw text. Re-ingesting identical content is idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to fetch and ingest | |
| text | No | Raw document text to ingest | |
| source | No | Source slug (e.g. zerodha) | |
| title | No | Document title |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In the absence of annotations, the description carries the full burden. It discloses the pipeline (chunk, embed, upsert) and idempotency. However, it omits potential side effects, authorization requirements, rate limits, or error conditions, which are relevant for an ingestion 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?
The description is a single, information-dense sentence with no filler. Every phrase adds value: the process, the input alternatives, and the idempotency guarantee. It is well-structured and front-loaded.
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?
For a tool with 4 optional params, no output schema, and no annotations, the description covers the core process and idempotency but lacks details on return values, error handling, size limits, or post-ingestion state changes. It is adequate but not complete for an agent to fully anticipate behavior.
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?
With 100% schema coverage, baseline is 3. The description adds value by clarifying that url and text are alternatives ('Provide either a URL ... or raw text'), which is not explicit in the schema. It does not elaborate on source or title beyond their schema descriptions.
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 the action ('Chunk → embed → upsert') and the resource ('document into pgvector'). It mentions two content sources (URL or raw text). While it doesn't explicitly differentiate from siblings, the purpose is specific and distinct from the retrieval tools.
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 does not provide any guidance on when to use this tool versus its siblings (answer_question, search_docs). There is no mention of prerequisites, contexts, or exclusions, leaving the agent without direction on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic search over the indexed financial-docs corpus. Returns the top-k chunks with cosine similarity scores and source metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural-language search query | |
| k | No | Number of chunks to return (default from config) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses semantic search nature, output composition (chunks, scores, metadata), and search scope. However, it omits details like potential rate limits, authentication, or read-only nature, but is still fairly transparent 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the core action ('Semantic search') and includes key output information. No wasted words, highly efficient.
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?
For a simple 2-parameter tool, the description adequately covers purpose, output, and scope. However, it doesn't specify the default value for k ('from config' is vague) and lacks detail on 'source metadata,' leaving minor gaps.
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 100% (both query and k have descriptions). The description adds no extra semantic detail beyond what's in the schema; it merely restates the operation. Baseline 3 is appropriate.
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 the tool performs 'semantic search' over a specific corpus ('financial-docs') and returns 'top-k chunks with cosine similarity scores and source metadata,' distinguishing it from siblings like answer_question (likely answering) and ingest_doc (adding documents).
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 implies usage for retrieval but lacks explicit when-to-use or when-not-to-use guidance compared to sibling tools. No alternatives mentioned, so it's adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a distinct purpose: ingestion, search, and question-answering. No functional overlap.
All tool names follow a consistent verb_noun pattern in snake_case: answer_question, ingest_doc, search_docs.
Three tools is well-scoped for a document Q&A server, each providing essential functionality without excess.
Core lifecycle (ingest, search, answer) is covered, but missing delete or update operations for documents is a minor gap.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for VC pitch-deck scoring, thesis-fit matching, and deal-flow management.
MCP server for querying Forkast documentation
Team docs served to AI agents over MCP - search, Markdown reads, version pinning, read audit.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/singhh879/findocs-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
