TechDoc Library MCP Server v1

TechDoc Library MCP Server is a Linux-oriented MCP service for managing a technical document library. It ingests original document files plus metainfo, stores versioned state in PostgreSQL, runs optional provider-driven extraction and enrichment on the server, and exposes version-aware retrieval through an MCP facade.

Architecture

The service is organized into four cooperating layers:

• MCP Facade - the external tool surface and request/response adapter
• Processing Orchestrator - workflow coordination for ingest, delete, reindex, and provider branches
• Document Library Engine - authoritative persistence, versioning, search, and retrieval logic
• Provider Layer - optional external adapters for extraction and metadata enrichment

The runtime flow is:

1. MCP requests enter the facade.
2. The facade validates payloads and routes them to orchestrator or engine services.
3. The orchestrator coordinates optional provider branches and operational workflows.
4. The engine persists documents, versions, metadata, searchable text, and audit events.
5. Retrieval returns version-aware document snapshots and search hits.

Local development can use a Python virtual environment, and production deployment also runs the service from a dedicated virtual environment under the techlib service account via systemd.

Repository Structure

• src/techlib_mcpserver/app/ - application bootstrap, config, and logging
• src/techlib_mcpserver/mcp_facade/ - MCP schemas and routing
• src/techlib_mcpserver/orchestrator/ - ingest, delete, extraction, enrichment, and reindex workflows
• src/techlib_mcpserver/engine/ - document persistence, versioning, metadata, search, and retrieval services
• src/techlib_mcpserver/providers/ - provider contracts, registry, and HTTP adapters
• src/techlib_mcpserver/persistence/ - SQLAlchemy models, repositories, and DB helpers
• src/techlib_mcpserver/search/ - indexing and embedding abstractions
• src/techlib_mcpserver/files/ - object storage abstraction for original files
• src/techlib_mcpserver/contracts/ - shared domain vocabulary
• src/techlib_mcpserver/utils/ - shared utilities, including release packaging helpers

Core Components

• app wires configuration, bootstrap, and the FastAPI runtime.
• mcp_facade translates MCP requests into internal service calls and shapes responses.
• orchestrator owns workflow policy and optional provider execution.
• engine is the only persistence boundary that writes library state. Ingest stores the original file bytes first, then providers refresh searchable state.
• providers stay opaque to the core system and never write directly to the library database.
• persistence exposes the PostgreSQL schema and repository layer.
• search provides the searchable representation and retrieval seams.
• files owns storage of original document bytes.

Document Metainfo

Ingest requests use metadata.subjects as the structured subject description for a document. Keep document_type_name separate from subject data.

A subject item captures the equipment context for the document and can include:

• vendor_name
• equipment_type
• model
• model_family
• subject_payload for opaque extensions

The engine denormalizes the main subject fields for search and catalog queries while keeping the full subject payload available for future expansion.

Server-Side Text Extraction

The built-in extraction provider runs on the server during ingest and materializes a structured content section for the document representation.

That content payload carries:

• native_text for direct text extraction
• ocr_text for OCR fallback
• merged_text as the canonical searchable text
• language_hint for ru, en, mixed, or unknown
• confidence and pages[] for provenance and debugging

The provider uses a strategy chain:

• direct extraction for PDF, DOCX, TXT, and similar formats
• OCR fallback for scanned PDFs and image files when OCR support is available

The core engine persists the provider payload as opaque data and refreshes searchable representation after each successful extraction step.

Integrations

The project integrates with:

• FastAPI for the runtime service
• SQLAlchemy 2.x and Alembic for PostgreSQL persistence and migrations
• psycopg for PostgreSQL connectivity
• Pydantic v2 and pydantic-settings for config and facade models
• optional HTTP-based extraction and enrichment providers
• systemd for Linux deployment

Documentation Map

• Usage Guide
• Windows Ingest Client
• Deployment Guide
• PostgreSQL Operations
• Content Delivery

The repository is intentionally compact, but the architecture and operational boundaries are already in place for the full v1 flow.