Implement Document Retrieval Services #7509

Author: tobiu

.github/ISSUE/epic-architect-knowledge-base-as-mcp.md

@@ -35,3 +35,4 @@ We will employ a rapid and agile development approach. The scope and API specifi
     - `ticket-kb-implement-delete-db-service.md`: Implement the service to delete the ChromaDB collection.
     - `ticket-kb-implement-query-service.md`: Implement the service to query documents from the knowledge base.
     - `ticket-kb-implement-sync-service.md`: Implement the service to build and embed the knowledge base content.
+    - `ticket-kb-implement-document-services.md`: Implement services to list and retrieve individual documents.

.github/ISSUE/ticket-kb-implement-document-services.md

@@ -0,0 +1,29 @@
+---
+title: Implement Document Retrieval Services
+labels: enhancement, AI
+---
+
+Parent epic: #7501
+GH ticket id: #7509
+
+**Phase:** 2
+**Assignee:** tobiu
+**Status:** Done
+
+## Description
+
+This ticket covers the implementation of the previously optional document retrieval endpoints. This will provide essential tools for inspecting and debugging the contents of the knowledge base.
+
+Two distinct tools will be created:
+1.  `list_documents`: To list documents from the collection, with support for pagination.
+2.  `get_document_by_id`: To retrieve a single document by its unique ID.
+
+## Acceptance Criteria
+
+1.  The `openapi.yaml` file is updated with two new endpoints:
+    - `GET /documents`
+    - `GET /documents/{id}`
+2.  The endpoints have `operationId`s of `list_documents` and `get_document_by_id` respectively.
+3.  A new `ai/mcp/server/knowledge-base/services/documentService.mjs` file is created.
+4.  The service contains `listDocuments` and `getDocumentById` functions.
+5.  The `toolService.mjs` `serviceMapping` is updated to point the new `operationId`s to their respective service functions.

ai/mcp/server/knowledge-base/openapi.yaml

@@ -138,6 +138,79 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
 
+  /documents:
+    get:
+      summary: List Documents
+      operationId: list_documents
+      x-annotations:
+        readOnlyHint: true
+      description: |
+        Retrieves a paginated list of all documents from the knowledge base collection.
+      tags: [Documents]
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          description: The maximum number of documents to return.
+          schema:
+            type: integer
+            default: 100
+        - name: offset
+          in: query
+          required: false
+          description: The number of documents to skip for pagination.
+          schema:
+            type: integer
+            default: 0
+      responses:
+        '200':
+          description: A paginated list of documents.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DocumentListResponse'
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /documents/{id}:
+    get:
+      summary: Get Document by ID
+      operationId: get_document_by_id
+      x-annotations:
+        readOnlyHint: true
+      description: Retrieves a single document from the collection by its unique ID.
+      tags: [Documents]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: The unique ID of the document to retrieve.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The requested document.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Document'
+        '404':
+          description: Document not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
 components:
   schemas:
     HealthCheckResponse:
@@ -195,6 +268,26 @@ components:
           items:
             $ref: '#/components/schemas/QueryResultItem'
 
+    Document:
+      type: object
+      properties:
+        id:
+          type: string
+        metadata:
+          type: object
+        content:
+          type: string
+
+    DocumentListResponse:
+      type: object
+      properties:
+        count:
+          type: integer
+        documents:
+          type: array
+          items:
+            $ref: '#/components/schemas/Document'
+
     SuccessResponse:
       type: object
       properties:

ai/mcp/server/knowledge-base/services/documentService.mjs

@@ -0,0 +1,58 @@
+import { ChromaClient } from 'chromadb';
+import aiConfig from '../../../../buildScripts/ai/aiConfig.mjs';
+
+/**
+ * Retrieves a paginated list of all documents from the knowledge base collection.
+ * @param {object} params - The parameters for listing documents.
+ * @param {number} [params.limit=100] - The maximum number of documents to return.
+ * @param {number} [params.offset=0] - The number of documents to skip for pagination.
+ * @returns {Promise<object>} A promise that resolves to the list of documents.
+ */
+async function listDocuments({ limit = 100, offset = 0 } = {}) {
+    const dbClient = new ChromaClient();
+    const collection = await dbClient.getCollection({ name: aiConfig.knowledgeBase.collectionName });
+
+    const results = await collection.get({
+        limit: limit,
+        offset: offset,
+        include: ["metadatas", "documents"]
+    });
+
+    const documents = results.ids.map((id, index) => ({
+        id: id,
+        metadata: results.metadatas[index],
+        content: results.documents[index]
+    }));
+
+    return {
+        count: documents.length,
+        documents: documents
+    };
+}
+
+/**
+ * Retrieves a single document from the collection by its unique ID.
+ * @param {string} id - The unique ID of the document to retrieve.
+ * @returns {Promise<object>} A promise that resolves to the requested document.
+ */
+async function getDocumentById({ id }) {
+    const dbClient = new ChromaClient();
+    const collection = await dbClient.getCollection({ name: aiConfig.knowledgeBase.collectionName });
+
+    const result = await collection.get({
+        ids: [id],
+        include: ["metadatas", "documents"]
+    });
+
+    if (result.ids.length === 0) {
+        throw new Error(`Document with id '${id}' not found.`);
+    }
+
+    return {
+        id: result.ids[0],
+        metadata: result.metadatas[0],
+        content: result.documents[0]
+    };
+}
+
+export { listDocuments, getDocumentById };

ai/mcp/server/knowledge-base/services/toolService.mjs

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'url';
 import * as healthService from './healthService.mjs';
 import * as databaseService from './databaseService.mjs';
 import * as queryService from './queryService.mjs';
+import * as documentService from './documentService.mjs';
 
 const __filename      = fileURLToPath(import.meta.url);
 const __dirname       = path.dirname(__filename);
@@ -26,15 +27,15 @@ const serviceMapping = {
     healthcheck    : healthService.healthcheck,
     sync_database  : databaseService.syncDatabase,
     delete_database: databaseService.deleteDatabase,
-    query_documents: queryService.queryDocuments
+    query_documents: queryService.queryDocuments,
+    list_documents: documentService.listDocuments,
+    get_document_by_id: documentService.getDocumentById
 };
 
 /**
  * Dynamically constructs a Zod schema for a tool's input arguments based on its
  * OpenAPI operation definition. This schema is used for robust runtime validation
  * of incoming tool call arguments.
- * @param {object} operation - The OpenAPI operation object.
- * @returns {z.ZodObject} A Zod object schema representing the tool's input.
  */
 function buildZodSchema(operation) {
     const shape = {};
@@ -311,7 +312,7 @@ async function callTool(toolName, args) {
     const validatedArgs = tool.zodSchema.parse(args);
 
     // Special handling for tools that expect a single object argument.
-    if (toolName === 'query_documents') {
+    if (['query_documents', 'list_documents', 'get_document_by_id'].includes(toolName)) {
         return tool.handler(validatedArgs);
     }