# 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.

```bash
# 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:

```bash
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`

```bash
# 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

```bash
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.
5. **SSE transport** — Centralised server deployment for the whole org.
6. **Audit log to JSONL** — Append every tool call + outcome (timestamp, doc IDs, role, injection flags) to a file for compliance and debugging.
7. **Usage analytics tool** — Admin-only `get_usage_stats` tool that tracks popular queries, most-accessed docs, and zero-result searches to surface knowledge gaps.
8. **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.