feat(mcp): add public AI-Q MCP server

.agents/skills/aiq-maintain-ci/SKILL.md

@@ -38,16 +38,18 @@ keep the gate working and must not weaken security or review rules.
   commands CI mirrors.
 - `.github/workflows/ci.yml`: jobs `pre-commit`, `test` (pytest + coverage),
   `helm-lint`, `test-scripts`. The `pre-commit` job runs Ruff separately and
-  `SKIP=ruff-check,ruff-format,pytest,helm-lint pre-commit run --all-files` — so
-  pytest/helm-lint run as their own jobs, not via the hook.
+  skips the push-stage pytest and Helm hooks when it runs
+  `pre-commit run --all-files` — those checks run as their own jobs instead.
 - `.github/workflows/ui.yml`: jobs `install`, `lint`, `type-check`, `unit-test`,
   `build`.
 - `.github/workflows/skills-eval.yml`: the Skills Eval gate (push +
   `workflow_dispatch`; `detect-changes` path gate → `generate-datasets` spec
   validation → `harbor-eval` on the self-hosted `aiq-eval` runner).
 - `.github/workflows/request-nvskills-ci.yml`: comment-triggered NVSkills CI.
-- `.pre-commit-config.yaml`: the hook set. Note `pytest` and `helm-lint` are
-  `stages: [push]` (see the reference for what that means locally).
+- `.pre-commit-config.yaml`: the hook set. Note `pytest-root`, `pytest-mcp`, and
+  `helm-lint` are `stages: [push]` (see the reference for what that means
+  locally). Root and MCP pytest checks use their own uv projects; MCP is not a
+  root dependency group.
 - `.github/CODEOWNERS`, `.coderabbit.yaml`, `.github/copy-pr-bot.yaml`: review
   routing, path-scoped automated review, and the PR mirror.
 

.agents/skills/aiq-maintain-ci/references/workflows-and-hooks.md

@@ -13,8 +13,10 @@ Authoritative sources: the workflow files under `.github/workflows/` and
 - `ci.yml` ("AIQ CI") — jobs: `pre-commit`, `test` (pytest with a coverage gate),
   `helm-lint` (deploy charts), `test-scripts`. The `pre-commit` job does **not**
   run the full hook set: it runs `ruff check .` / `ruff format --check .`
-  separately and `SKIP=ruff-check,ruff-format,pytest,helm-lint pre-commit run
-  --all-files`, leaving pytest/helm-lint to their own jobs.
+  separately and skips the push-stage pytest and Helm hooks when it runs
+  `pre-commit run --all-files`, leaving those checks to their own jobs. The test
+  job syncs the root AI-Q environment from `uv.lock` and the independent MCP
+  environment from `mcp/uv.lock`.
 - `ui.yml` — jobs `install`, `lint`, `type-check`, `unit-test`, `build` for
   `frontends/ui/`.
 - `skills-eval.yml` ("Skills Eval") — runs on `push` and `workflow_dispatch`. A
@@ -35,15 +37,17 @@ bot-driven merge once repository rules pass. The mirror behavior is configured i
 
 `.pre-commit-config.yaml` is the source of truth. Default-stage hooks (run by a
 plain `pre-commit run`) include: `ruff-check`, `ruff-format`, `uv-lock`,
-`check-merge-conflict`, `check-added-large-files`, `check-yaml`,
+`uv-lock-mcp`, `check-merge-conflict`, `check-added-large-files`, `check-yaml`,
 `end-of-file-fixer`, `trailing-whitespace`, `detect-secrets`, `validate-skills`,
 `clear-notebook-output-cells`, and `markdown-link-check`.
 
-Two hooks — `pytest` and `helm-lint` — are `stages: [push]`, so a default
-`pre-commit run` / `pre-commit run --all-files` **skips them**. Include them
-explicitly with `pre-commit run --all-files --hook-stage push`. CI does not run
-them via the `pre-commit` job either (it `SKIP=`s them); they run as the dedicated
-`test` and `helm-lint` jobs in `ci.yml`.
+The root pytest, MCP pytest, and `helm-lint` hooks are `stages: [push]`, so a
+default `pre-commit run` / `pre-commit run --all-files` **skips them**. Include
+them explicitly with `pre-commit run --all-files --hook-stage push`. CI does not
+run them via the `pre-commit` job either; they run as the dedicated `test` and
+`helm-lint` jobs in `ci.yml`. The root pytest hook uses `uv.lock`; the MCP hook
+invokes `uv run --project mcp --extra dev pytest mcp/tests` against
+`mcp/uv.lock`.
 
 ## Validation
 

.agents/skills/aiq-release-qa/SKILL.md

@@ -35,8 +35,10 @@ boundaries — not to run every command every time.
   section is the source of truth for every command below.
 - [CONTRIBUTING.md](../../../CONTRIBUTING.md): "Local Validation" — the exact
   commands to run and the requirement to include their output in the PR.
-- `pyproject.toml`: Ruff config (line length 120, rule sets `E,F,W,I,PL,UP`)
-  and the dev dependency group used by `uv sync --group dev`.
+- `pyproject.toml` and `uv.lock`: root Ruff config (line length 120, rule sets
+  `E,F,W,I,PL,UP`) and the root dev environment.
+- `mcp/pyproject.toml` and `mcp/uv.lock`: the independent MCP runtime and dev
+  environment. MCP is not a root dependency group.
 - `frontends/ui/package.json`: the real `scripts` (`lint`, `type-check`,
   `test:ci`, `build`) — use these names, do not invent npm scripts.
 
@@ -67,12 +69,22 @@ uv run ruff format --check <changed paths> # format check
 uv run pytest <scoped test paths>          # tests
 ```
 
+MCP server (run from the repo root):
+
+```bash
+uv sync --project mcp --extra dev
+uv run ruff check mcp
+uv run ruff format --check mcp
+uv run --project mcp --extra dev pytest mcp/tests
+```
+
 Broaden to the whole tree when the change crosses shared boundaries:
 
 ```bash
 uv run ruff check .
 uv run ruff format --check .
 uv run pytest
+uv run --project mcp --extra dev pytest mcp/tests
 ```
 
 Frontend (from `frontends/ui/`):
@@ -89,8 +101,11 @@ matrix reference.
 
 ## Common Mistakes
 
-- Running the entire `uv run pytest` suite for a one-package change instead of
-  scoping to the touched paths first — slow, and it buries the relevant signal.
+- Running both complete root and MCP test suites for a one-package change
+  instead of scoping to the touched paths first — slow, and it buries the
+  relevant signal.
+- Running MCP tests in the root environment; use `uv run --project mcp` so the
+  check consumes the isolated MCP lock and dev extra.
 - Skipping `ruff format --check` and pushing unformatted code that fails CI.
 - Hand-reformatting unrelated code; only the changed code should move.
 - Forgetting that `nat eval` needs `deploy/.env`; run evals via

.agents/skills/aiq-release-qa/references/validation-matrix.md

@@ -13,8 +13,9 @@ Validation"); this file is a convenience index, not a new source of truth.
 ## One-time environment setup
 
 ```bash
-./scripts/setup.sh          # one-time environment setup
-uv sync --group dev         # ensure dev dependencies (ruff, pytest) are present
+./scripts/setup.sh                    # one-time environment setup
+uv sync --group dev                   # root AI-Q development environment
+uv sync --project mcp --extra dev     # independent MCP development environment
 ```
 
 ## Backend Python — `src/`, `sources/`, `tests/`
@@ -46,6 +47,19 @@ Expected: Ruff reports no lint or format failures for the changed code, and the
 selected tests pass. Ruff config (line length 120; rule sets `E,F,W,I,PL,UP`)
 lives in `pyproject.toml`.
 
+## MCP server — `mcp/`
+
+```bash
+uv sync --project mcp --extra dev
+uv run ruff check mcp
+uv run ruff format --check mcp
+uv run --project mcp --extra dev pytest mcp/tests
+```
+
+Set `AIQ_MCP_TEST_DB_URL` to a disposable PostgreSQL database to include the
+database-backed job, checkpoint, restart, and NAT-load tests. Those tests create
+and drop tables, so never point them at a service or production database.
+
 ## Web UI — `frontends/ui/`
 
 ```bash

.coderabbit.yaml

@@ -96,7 +96,7 @@ reviews:
         Review Agent Skill and skill-eval changes for valid skill metadata, deterministic eval specs, safe handling of
         credentials, and clear generated-output boundaries. Do not flag SKILL.md files for missing SPDX headers when the
         entrypoint intentionally starts with YAML frontmatter.
-    - path: "{.github/**,ci/**,.pre-commit-config.yaml,pyproject.toml,uv.lock}"
+    - path: "{.github/**,ci/**,.pre-commit-config.yaml,pyproject.toml,uv.lock,mcp/pyproject.toml,mcp/uv.lock}"
       instructions: |
         Review automation and packaging changes for least-privilege permissions, pinned versions where appropriate,
         copy-pr-bot pull-request/<N> branch behavior, reproducible uv/npm setup, secret handling, and consistency with

.dockerignore

@@ -12,6 +12,7 @@
 **/.env.*
 !.env.example
 !**/.env.example
+**/certs/
 
 # ---- Python ----
 __pycache__/
@@ -54,12 +55,14 @@ htmlcov/
 .tox/
 .ruff_cache/
 tests/
-frontends/benchmarks/
 
 # ---- Documentation (not needed at runtime) ----
 *.md
+!README.md
+!mcp/README.md
+!sources/knowledge_layer/README.md
+!sources/tavily_web_search/README.md
 docs/
-LICENSE
 license_report.pdf
 
 # ---- CI/CD & Deployment (not needed inside image) ----