---
id: 11644
title: Phase 5A — KB MCP Server Integration Test Parity with MC (pre-Phase-0/1 shippable)
state: CLOSED
labels:
  - enhancement
  - ai
  - testing
assignees:
  - neo-gpt
createdAt: '2026-05-19T12:08:38Z'
updatedAt: '2026-06-07T17:13:43Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11644'
author: neo-opus-ada
commentsCount: 0
parentIssue: 11643
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-19T15:00:34Z'
---
# Phase 5A — KB MCP Server Integration Test Parity with MC (pre-Phase-0/1 shippable)

## Context

Sub of Phase 5 Epic [#11643](https://github.com/neomjs/neo/issues/11643) (meta-Epic [#11624](https://github.com/neomjs/neo/issues/11624)).

**Pre-Phase-0/1 shippable — INDEPENDENT, can start NOW.** Validates KB MCP server foundation BEFORE Phase 0/1 evolves it. Substrate-correct safety net for the rest of the meta-Epic.

**Topology anchor:** Per [ADR 0003 — Chroma Topology Unified Only](../tree/dev/learn/agentos/decisions/0003-chroma-topology-unified-only.md), tests target the unified-Chroma topology: one ChromaDB daemon shared by KB + MC MCP servers (KB-owned `knowledge-base` collection vs MC-owned `neo-agent-memory` + `neo-agent-sessions`). Existing `composeWebServer.mjs` fixture already wraps unified-topology docker-compose.

## The Problem

**Calibrated 2026-05-19T13:42Z (GPT epic-review on #11643):** my initial framing of "zero KB references in `RemoteMcpTransport.integration.spec.mjs`" was incomplete V-B-A. That spec actually does call `query_documents` against `KB_URL` for transport tests (lines 4, 15, 21, 35) — KB has partial SSE-transport coverage already. So 5A's task is to SPLIT/EXTEND that surface, not duplicate it.

KB's `healthcheck.spec.mjs` (#10805 Lane A) gives dual-server dockerized healthcheck. `RemoteMcpTransport.integration.spec.mjs` gives partial SSE-transport `query_documents` coverage via `KB_URL`. The remaining MC integration specs lack KB equivalents:

- `RemoteMcpTransport.integration.spec.mjs` — SSE + stdio transport (partial KB coverage exists via `query_documents`; needs SPLIT/EXTEND, not duplicate — stdio path + tool-surface parity beyond `query_documents` + `ask_knowledge_base` not yet covered)
- `AuthRejection.integration.spec.mjs` — OIDC/proxy auth rejection
- `OidcAuth.integration.spec.mjs` — OIDC bearer authentication
- `BackupRestoreWipe.integration.spec.mjs` — backup/restore/wipe via JSONL
- `HeartbeatPropagation.integration.spec.mjs` — healthcheck propagation in unified topology

KB has equivalent surfaces (`manageDatabaseBackup` action: 'export'/'import'/'truncate' lines 236-409 of DatabaseService.mjs; KB MCP server via SSE/stdio; OIDC + proxy-header auth via shared `AuthService`) but no dedicated KB-side integration test coverage. Without it, Phase 0/1 work risks silently regressing these operational surfaces.

## The Fix

Create parallel KB integration test specs at `test/playwright/integration/`:

1. **`KBRemoteMcpTransport.integration.spec.mjs`** — KB MCP server stdio accessibility (NOT yet covered) + tool-surface parity beyond `query_documents` (e.g. `ask_knowledge_base`, `manage_knowledge_base`, `get_class_hierarchy`, `get_document_by_id`, `list_documents`); reuse the `KB_URL` partial SSE coverage already in `RemoteMcpTransport.integration.spec.mjs` as the precedent and extend rather than duplicate
2. **`KBAuthRejection.integration.spec.mjs`** — KB MCP server rejects unauthenticated requests; rejects wrong-identity OIDC tokens; rejects untrusted proxy-header injection
3. **`KBOidcAuth.integration.spec.mjs`** — KB MCP server with OIDC bearer authentication; identity stamped server-side; access to KB tools (manage_knowledge_base, ask_knowledge_base, query_documents, etc.) gated correctly
4. **`KBBackupRestoreWipe.integration.spec.mjs`** — KB manageDatabaseBackup action: 'export' produces JSONL; action: 'import' restores embeddings without re-embedding; action: 'truncate' clears with confirmation gate; mode: 'replace' / 'merge' semantics
5. **`KBHeartbeatPropagation.integration.spec.mjs`** — KB healthcheck under sustained-liveness probe; KB collection state in unified topology healthcheck.database.connection.collections.knowledgeBase block

Each test reuses existing fixtures:
- `fixtures/composeWebServer.mjs` (dockerized server wrapper)
- `fixtures/mcpClient.mjs` (MCP tool dispatch client)
- `util/assertSustainedHealth.mjs` (health-probe helper)

## Acceptance Criteria

- [ ] `KBRemoteMcpTransport.integration.spec.mjs` exists and passes; covers SSE + stdio
- [ ] `KBAuthRejection.integration.spec.mjs` exists and passes; covers 3 rejection paths
- [ ] `KBOidcAuth.integration.spec.mjs` exists and passes; covers OIDC happy path + identity stamping
- [ ] `KBBackupRestoreWipe.integration.spec.mjs` exists and passes; covers export/import/truncate via JSONL
- [ ] `KBHeartbeatPropagation.integration.spec.mjs` exists and passes; covers sustained-liveness + collection state
- [ ] All tests run via `npm run test-integration-unified` (NOT `npx playwright`; per memory anchor on test isolation)
- [ ] All tests skip cleanly when docker unavailable (`test.skip(readiness.dockerAvailable === false, ...)` pattern from healthcheck.spec.mjs)
- [ ] CI integration: failures gate Phase 0/1 work
- [ ] No parallel fixture infrastructure created; reuse existing 3 fixture/util helpers

## Out of Scope

- Phase 0/1 contracts integration tests → Phase 5B (post-Phase-0/1D)
- Cloud-ingestion-specific E2E tests → Phase 2F (#11638)
- Performance benchmarking
- Custom-source/parser registration tests → covered by Phase 0/1B (#11630) unit tests + Phase 5C cross-cutting coverage

## Related

- **Parent:** [#11643](https://github.com/neomjs/neo/issues/11643)
- **Reference precedent:** [#10805](https://github.com/neomjs/neo/issues/10805) Lane A (`healthcheck.spec.mjs` pattern); MC integration specs are the parallel templates
- **Existing fixtures:** `test/playwright/integration/fixtures/composeWebServer.mjs`, `mcpClient.mjs`, `util/assertSustainedHealth.mjs`

## Origin Session ID

`7360e917-1733-4cdd-a6f3-5ac51c34b838`

## Handoff Retrieval Hints

- Adapt each MC integration spec for KB endpoint + KB tool surface. The dispatch pattern is identical (MCP JSON-RPC); only endpoints + tool names + assertion targets differ.
- Start with `KBBackupRestoreWipe.integration.spec.mjs` — `manageDatabaseBackup` already exists; lowest-implementation-risk for first parity test
- `KBAuthRejection` + `KBOidcAuth` share auth substrate with MC equivalents via shared `AuthService` — most code is reusable

## Timeline

- 2026-05-19T12:08:40Z @neo-opus-ada added the `enhancement` label
- 2026-05-19T12:08:40Z @neo-opus-ada added the `ai` label
- 2026-05-19T12:08:40Z @neo-opus-ada added the `testing` label
- 2026-05-19T12:09:41Z @neo-opus-ada added parent issue #11643
- 2026-05-19T12:10:35Z @neo-opus-ada cross-referenced by #11624
- 2026-05-19T13:38:30Z @neo-gpt cross-referenced by #11643
- 2026-05-19T13:39:28Z @neo-gpt assigned to @neo-gpt
- 2026-05-19T14:00:20Z @neo-gpt referenced in commit `b1eac44` - "test(kb): cover KB stdio transport probe (#11644)

Adds a KB stdio list-tools probe to complement the Docker-gated SSE remote transport assertions. Keeps the SSE readiness skip local to the Docker-backed test so stdio coverage remains executable without Docker.

Co-Authored-By: neo-gpt <neo-gpt@neomjs.com>"
- 2026-05-19T14:01:49Z @neo-gpt cross-referenced by PR #11648
- 2026-05-19T14:26:05Z @neo-gpt referenced in commit `1af8bb1` - "fix(kb): stabilize KB integration CI fixtures (#11644)"
- 2026-05-19T14:35:58Z @neo-gpt referenced in commit `50fabc6` - "fix(kb): keep backup restore fixture collection stable (#11644)"
- 2026-05-19T15:00:33Z @tobiu referenced in commit `4359a77` - "test(kb): add KB integration parity coverage (#11644) (#11648)

* feat(kb): add KB integration parity specs (#11644)

Adds KB-prefixed Dockerized integration specs for remote MCP transport, proxy-auth rejection, OIDC auth, backup/truncate/restore, and sustained health propagation. Extends the integration compose stack with a KB OIDC server and readiness probe on port 13003.

Co-Authored-By: neo-gpt <neo-gpt@neomjs.com>

* test(kb): cover KB stdio transport probe (#11644)

Adds a KB stdio list-tools probe to complement the Docker-gated SSE remote transport assertions. Keeps the SSE readiness skip local to the Docker-backed test so stdio coverage remains executable without Docker.

Co-Authored-By: neo-gpt <neo-gpt@neomjs.com>

* fix(kb): stabilize KB integration CI fixtures (#11644)

* fix(kb): keep backup restore fixture collection stable (#11644)

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-19T15:00:34Z @tobiu closed this issue
- 2026-05-21T00:32:18Z @neo-opus-ada cross-referenced by PR #11703
- 2026-05-22T11:09:29Z @neo-opus-ada cross-referenced by PR #11760
- 2026-05-22T12:59:12Z @neo-opus-ada cross-referenced by #11725
- 2026-05-22T13:02:46Z @neo-opus-ada cross-referenced by #11720

