Business Data MCP

An evidence-first Model Context Protocol server for private business documents and structured datasets. The server preserves original files, deterministic extraction, normalized business concepts, and source lineage instead of reducing every upload to document-chat chunks.

See architecture, operations, security, and MCP client configuration.

Implemented capabilities include immutable/versioned ingestion for CSV, XLSX, TXT, DOCX and text-based PDF; Parquet-backed safe tabular queries; source lineage; bilingual semantic mapping suggestions with user confirmation; PostgreSQL full-text plus pgvector hybrid retrieval; OpenRouter summaries/embeddings/analysis with strict validation and usage tracking; OAuth/PKCE and scoped MCP credentials; Streamable HTTP and stdio MCP; and soft-delete/restore/retention workflows.

Workspace administrators can manage sources through the server-rendered UI at /admin. The source list and detail pages report successful per-source MCP usage from the audit trail; counting starts after the usage-tracking migration is deployed.

Containers

The production-oriented Compose stack runs the API, worker, scheduler, migrations, PostgreSQL with pgvector, Redis, MinIO, ClamAV, and Caddy. Upstream images are pinned by digest, application processes run as a fixed non-root user with a read-only root filesystem, and only Caddy publishes host ports.

See the operations guide for secret setup, startup, health checks, backups, image updates, and shutdown.

Development

Requirements: Python 3.12, PostgreSQL with pgvector, Redis, and S3-compatible object storage. Docker Compose provides the infrastructure services.

python -m venv .venv
.venv/bin/pip install -e '.[dev]'
docker compose -f deploy/compose.yaml up -d postgres redis minio clamav
alembic upgrade head
business-data-api

Run validation with:

ruff check .
mypy src
pytest

Uploaded files are untrusted input. Do not expose development deployments to the internet or use the development secrets in production.