Skip to main content
Glama
Internal Documentation Search

Internal Documentation Search

by aklianeva

Internal Documentation Search — MCP Server

What's in the box: An MCP server with 5 tools, 3 prompt templates, and 2 resources backed by a knowledge base of 16 markdown documents (standards, runbooks, ADRs). Includes RBAC with 3 roles, sliding-window rate limiting, input sanitisation, and a CLI scraper to ingest docs from URLs. RAG (ChromaDB) is available as an optional extra — keyword search works well for structured docs with clear titles and tags, but RAG adds value when engineers phrase queries differently from how documents are written (e.g. searching "why do we use Kafka" against an ADR titled "Adopt Event-Driven Architecture").

An MCP server that exposes an internal knowledge base to AI assistants, enabling engineers to search standards, runbooks, and architecture decisions from within their coding workflow.

Why this scenario? Finding internal docs is one of the highest-friction points for engineers. This brings company-specific knowledge directly into the AI assistant, keeping engineers in flow.

Architecture

AI Assistant ◄──MCP (stdio)──► MCP Server
                                 ├─ config.py   (Pydantic BaseSettings)
                                 ├─ auth.py     (RBAC + rate limiting)
                                 ├─ models.py   (Document, Category, enums)
                                 ├─ server.py   (tools, prompts, resources)
                                 ├─ scraper.py  (CLI: scrape URLs → markdown)
                                 └─ kb/         (knowledge base sub-package)
                                      ├─ store.py   (document store + search)
                                      ├─ loader.py  (markdown file loader)
                                      └─ rag.py     (ChromaDB vector search)

Documents are stored as markdown files with YAML frontmatter in docs/knowledge_base/ (16 docs: 6 Standards, 5 Runbooks, 5 ADRs). They are loaded at startup by the document loader.

Tools

Tool

Purpose

search_internal_docs

Free-text search with optional category/tag filters, ranked by relevance

get_document

Full document content by ID, with semantically related docs

list_doc_categories

Available categories

list_doc_tags

All tags for refining searches

list_all_docs

Browse all documents, optionally by category

Prompts

Prompt

Purpose

investigate_incident

Structured incident investigation using runbooks

check_code_standards

Review code against internal standards

explain_architecture_decision

Explain why a technology was adopted (ADRs)

Resources

  • docs://categories — list of categories

  • docs://document/{doc_id} — individual document access

RAG (optional)

When enabled, search uses hybrid ranking — keyword scoring blended with ChromaDB vector similarity. Related documents in get_document are found via semantic similarity instead of hardcoded lists.

# Install with RAG support
uv pip install -e '.[rag]'

# Run with RAG enabled
RAG_ENABLED=true uv run internal-docs-mcp

Scraping new documents

Scrape any URL into a knowledge base markdown file:

uv pip install -e '.[scrape]'

internal-docs-scrape https://example.com/some-doc \
    --id EXT-001 \
    --title "External Integration Guide" \
    --category standard \
    --tags integration,api

Files are saved to docs/knowledge_base/ and loaded automatically on next server start.

Setup

Prerequisites: Python 3.12+, uv (recommended) or pip

# Install (core)
uv pip install -e '.[dev]'

# Install all extras (RAG + scraping)
uv pip install -e '.[all]'

# Run
python -m internal_docs_mcp

# Test
uv run pytest tests/ -v

# Lint
uv run ruff check src/ tests/

Connect to Claude Code

claude mcp add internal-docs /path/to/internal-docs-mcp/run_server.sh

What I Would Improve

Note: This project uses local markdown files as the data source to keep the demo self-contained. In a real production setup the MCP server would connect to live APIs and databases — e.g. Confluence/GitLab wikis, PostgreSQL, Elasticsearch — so engineers always get up-to-date results without manual file management.

  1. Real data source — Connect to Confluence/GitLab wikis via API with a Redis cache.

  2. RBAC via SSO — Map caller identity from SSO tokens instead of static API keys.

  3. Prompt injection classifier — Add Lakera Guard or similar instead of relying on character-level sanitisation.

  4. Document freshness — Flag docs not updated in >6 months as potentially stale in search results.

  5. Tag match mode — Add tag_match parameter ("any" vs "all") to search_internal_docs so tags=["kafka","kubernetes"] can return docs matching either tag.

  6. Feedback loop — Thumbs-up/down on results to improve ranking.

  7. SSE transport — Centralised server deployment for the whole org.

  8. Audit log to JSONL — Append every tool call + outcome (timestamp, doc IDs, role, injection flags) to a file for compliance and debugging.

  9. Usage analytics tool — Admin-only get_usage_stats tool that tracks popular queries, most-accessed docs, and zero-result searches to surface knowledge gaps.

  10. Onboarding prompt — onboard_engineer(team, role) prompt template that guides new hires to relevant standards + ADRs for their team without knowing what to search for.

Available Tools

5 tools
get_documentA

Retrieve an internal document by its ID.

Use this after search_internal_docs to get details of a specific document. Document IDs follow the format: STD-001, RUN-002, ADR-003, etc.

Args: document_id: The document identifier (e.g., "STD-001", "RUN-002"). summary: When True, return only a summary (first 500 chars) instead of the full content. Useful for long documents to save context.

Returns: JSON string with the document content (or summary), or an error if not found.

Inputs: document_id (required), summary. Returns: result

list_all_docsA

List all documents in the knowledge base, optionally filtered by category.

Use this to get an overview of everything available. For specific questions, prefer search_internal_docs instead.

Args: category: Optional filter — one of "standard", "runbook", or "adr".

Returns: JSON string with document summaries.

Inputs: category. Returns: result

list_doc_categoriesA

List all available documentation categories with descriptions.

Use this to understand what kinds of documents are available in the knowledge base before searching.

Returns: JSON string with available categories and their descriptions.

Inputs: no named parameters. Returns: result

list_doc_tagsA

List all available tags used across internal documents.

Use this to discover what topics are covered and to refine searches with tag filters.

Returns: JSON string with all available tags sorted alphabetically.

Inputs: no named parameters. Returns: result

search_internal_docsA

Search the internal knowledge base for standards, runbooks, and architecture decisions.

Use this tool when an engineer asks about:

  • How something should be done (standards)

  • How to respond to an incident (runbooks)

  • Why an architectural choice was made (ADRs)

Args: query: Free-text search query describing what the engineer is looking for. category: Optional filter — one of "standard", "runbook", or "adr". tags: Optional list of tags to filter by (e.g. ["python", "security"]).

Returns: JSON string with matching documents (summaries) or a not-found message.

Inputs: query (required), category, tags. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: get_document retrieves a specific document, list_all_docs lists all documents, list_doc_categories lists categories, list_doc_tags lists tags, and search_internal_docs searches documents. The descriptions explicitly differentiate them, such as noting to use search_internal_docs for specific questions instead of list_all_docs.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case: get_document, list_all_docs, list_doc_categories, list_doc_tags, and search_internal_docs. The verbs (get, list, search) are used appropriately and predictably across the set.

    Tool Count5/5

    With 5 tools, this server is well-scoped for internal documentation search, covering core operations like retrieval, listing, categorization, tagging, and searching. Each tool earns its place without redundancy or bloat, fitting typical needs for a knowledge base interface.

    Completeness5/5

    The tool surface is complete for the domain of internal documentation search, covering all essential CRUD-like operations: listing (list_all_docs, list_doc_categories, list_doc_tags), retrieving (get_document), and searching (search_internal_docs). There are no obvious gaps, and the tools support filtering and summarization for efficient agent workflows.

    Related MCP Connectors