enterprise-context-mcp-admin

FastAPI REST API that owns all write operations on the shared enterprise knowledge base stored in DuckDB. It is the companion writer service to enterprise-context-mcp, which exposes the same database as a read-only MCP server for LLMs.

Single-writer constraint — deploy with replicas: 1. DuckDB does not support concurrent writers.

---

Overview

The knowledge base stores enterprise process rules and guidelines (CI/CD standards, security policies, Git conventions, architecture guidelines, etc.) that LLM-powered tools can query at runtime. This service is the human-facing side: engineers and automation pipelines use it to populate and maintain the data.

┌─────────────────────────────────┐      ┌───────────────────────────┐
│  enterprise-context-mcp-admin   │      │   enterprise-context-mcp  │
│  (FastAPI  ·  READ_WRITE)       │─────▶│   (FastMCP  ·  READ_ONLY) │
│  replicas: 1                    │  DB  │   replicas: N             │
└─────────────────────────────────┘      └───────────────────────────┘
              │                                        │
              └──────────────┐ ┌─────────────────────┘
                             ▼ ▼
                      enterprise.duckdb
                      (shared PVC / file)

---

Features

• Knowledge entries — full CRUD + bulk import across 6 knowledge domains
• Categories — pre-seeded domains (development_process, cicd, security, production_readiness, git_pr, architecture)
• Roles — audience tagging (developer, devops, architect, manager)
• Tags — free-form labels created automatically on entry upsert
• Schema ownership — DDL and seed data run at startup; the MCP reader has no write access
• Auto-generated docs — Swagger UI at /docs, ReDoc at /redoc

---

Tech Stack

Component	Version
Python	3.13
FastAPI	≥ 0.115
DuckDB	≥ 1.2.0
Uvicorn	≥ 0.32
UV	package manager

---

Project Structure

enterprise-context-mcp-admin/
├── main.py          # FastAPI app, router registration, /health endpoint
├── db.py            # DuckDB lifespan, schema DDL, seed data, Depends helpers
├── models.py        # Pydantic request/response models
├── seed.py          # Idempotent script to populate placeholder entries
├── routers/
│   ├── entries.py   # GET/POST /entries, POST /entries/bulk, GET/PATCH/DELETE /entries/{id}
│   ├── categories.py# GET/POST /categories, DELETE /categories/{id}
│   ├── roles.py     # GET/POST /roles, DELETE /roles/{id}
│   └── tags.py      # GET /tags, DELETE /tags/{id}
├── pyproject.toml
└── uv.lock

---

Getting Started

Prerequisites

• UV installed (curl -LsSf https://astral.sh/uv/install.sh | sh)

Install dependencies

uv sync

Run the server

ENTERPRISE_DB_PATH=./enterprise.duckdb uv run uvicorn main:app --reload

The API will be available at http://localhost:8000. Open http://localhost:8000/docs for the interactive Swagger UI.

Seed placeholder entries

uv run python seed.py

This inserts 19 placeholder knowledge entries (one per MCP tool) and is idempotent — safe to run multiple times.

---

Environment Variables

Variable	Default	Description
ENTERPRISE_DB_PATH	./enterprise.duckdb	Absolute or relative path to the DuckDB file

In Kubernetes, set this to the mount path of the shared PVC so both the admin and MCP reader services access the same file.

---

API Reference

Health

Method	Path	Description
GET	/health	Liveness/readiness check

Entries

Method	Path	Description
GET	/entries	List entries (filter by category, role, tag, search; paginate with skip/limit)
POST	/entries	Create a single entry
POST	/entries/bulk	Bulk import a list of entries
GET	/entries/{id}	Get a single entry by ID
PATCH	/entries/{id}	Partially update an entry
DELETE	/entries/{id}	Delete an entry

Categories

Method	Path	Description
GET	/categories	List all categories
POST	/categories	Create a category
DELETE	/categories/{id}	Delete a category (rejected if entries exist)

Roles

Method	Path	Description
GET	/roles	List all roles
POST	/roles	Create a role
DELETE	/roles/{id}	Delete a role

Tags

Method	Path	Description
GET	/tags	List all tags
DELETE	/tags/{id}	Delete a tag

---

Schema

categories ──< knowledge_entries >── entry_roles >── roles
                                 └── entry_tags  >── tags

• knowledge_entries references categories (NOT NULL)
• entry_roles and entry_tags are junction tables
• Foreign keys do not use CASCADE (DuckDB limitation) — deletions are handled explicitly in the API layer

---

Deployment (Kubernetes)

# Single-writer constraint
spec:
  replicas: 1
  containers:
    - name: admin
      env:
        - name: ENTERPRISE_DB_PATH
          value: /data/enterprise.duckdb
      volumeMounts:
        - name: db-storage
          mountPath: /data

Both the admin and MCP reader deployments must mount the same PVC at the path pointed to by ENTERPRISE_DB_PATH.

---

Related

• enterprise-context-mcp — the read-only MCP server that exposes this database to LLMs

---

License

MIT