Merge pull request #2 from stefanoamorelli/feat/document-endpoints

Author: stefanoamorelli

src/api/client.ts

@@ -5,6 +5,7 @@ import { OfficersApiClient } from './officers-api.js';
 import { FilingApiClient } from './filing-api.js';
 import { ChargesApiClient } from './charges-api.js';
 import { PSCApiClient } from './psc-api.js';
+import { DocumentApiClient } from './document-api.js';
 
 export class CompaniesHouseApiClient {
   public company: CompanyApiClient;
@@ -13,6 +14,7 @@ export class CompaniesHouseApiClient {
   public filing: FilingApiClient;
   public charges: ChargesApiClient;
   public psc: PSCApiClient;
+  public document: DocumentApiClient;
 
   constructor(config: ApiConfig) {
     this.company = new CompanyApiClient(config);
@@ -21,6 +23,7 @@ export class CompaniesHouseApiClient {
     this.filing = new FilingApiClient(config);
     this.charges = new ChargesApiClient(config);
     this.psc = new PSCApiClient(config);
+    this.document = new DocumentApiClient(config);
   }
 
   async testConnection(): Promise<boolean> {

src/api/document-api.ts

@@ -0,0 +1,23 @@
+import { BaseApiClient } from './base-client.js';
+import type {
+  DocumentMetadata,
+  DocumentContent,
+  DocumentMetadataResponse
+} from '../types/document.js';
+
+export class DocumentApiClient extends BaseApiClient {
+  async getDocumentMetadata(params: DocumentMetadata): Promise<DocumentMetadataResponse> {
+    const response = await this.client.get(`/document/${params.document_id}`);
+    return response.data;
+  }
+
+  async getDocumentContent(params: DocumentContent): Promise<Buffer> {
+    const response = await this.client.get(`/document/${params.document_id}/content`, {
+      responseType: 'arraybuffer',
+      headers: {
+        Accept: 'application/pdf'
+      }
+    });
+    return Buffer.from(response.data);
+  }
+}

src/handlers/document-handlers.ts

@@ -0,0 +1,32 @@
+import { CompaniesHouseApiClient } from '../api/client.js';
+import * as schemas from '../types/document.js';
+
+export class DocumentHandlers {
+  constructor(private apiClient: CompaniesHouseApiClient) {}
+
+  async handleGetDocumentMetadata(args: unknown) {
+    const params = schemas.DocumentMetadataSchema.parse(args);
+    const result = await this.apiClient.document.getDocumentMetadata(params);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(result, null, 2)
+        }
+      ]
+    };
+  }
+
+  async handleGetDocumentContent(args: unknown) {
+    const params = schemas.DocumentContentSchema.parse(args);
+    const result = await this.apiClient.document.getDocumentContent(params);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Document content retrieved (${result.length} bytes). Content is binary PDF data.`
+        }
+      ]
+    };
+  }
+}

src/mcp-server.ts

@@ -9,6 +9,7 @@ import { OfficersHandlers } from './handlers/officers-handlers.js';
 import { FilingHandlers } from './handlers/filing-handlers.js';
 import { ChargesHandlers } from './handlers/charges-handlers.js';
 import { PSCHandlers } from './handlers/psc-handlers.js';
+import { DocumentHandlers } from './handlers/document-handlers.js';
 
 export interface ServerConfig {
   apiKey: string;
@@ -24,6 +25,7 @@ export class CompaniesHouseMCPServer {
   private filingHandlers: FilingHandlers;
   private chargesHandlers: ChargesHandlers;
   private pscHandlers: PSCHandlers;
+  private documentHandlers: DocumentHandlers;
 
   constructor(config: ServerConfig) {
     this.server = new Server(
@@ -50,6 +52,7 @@ export class CompaniesHouseMCPServer {
     this.filingHandlers = new FilingHandlers(this.apiClient);
     this.chargesHandlers = new ChargesHandlers(this.apiClient);
     this.pscHandlers = new PSCHandlers(this.apiClient);
+    this.documentHandlers = new DocumentHandlers(this.apiClient);
 
     this.setupHandlers();
   }
@@ -146,6 +149,12 @@ export class CompaniesHouseMCPServer {
           case 'get_psc_super_secure':
             return await this.pscHandlers.handleGetPSCSuperSecure(args);
 
+          // Document endpoints
+          case 'get_document_metadata':
+            return await this.documentHandlers.handleGetDocumentMetadata(args);
+          case 'get_document_content':
+            return await this.documentHandlers.handleGetDocumentContent(args);
+
           default:
             throw new Error(`Unknown tool: ${name}`);
         }

src/tools/tools-definition.ts

@@ -755,13 +755,47 @@ export function getPSCTools(): Tool[] {
   ];
 }
 
+export function getDocumentTools(): Tool[] {
+  return [
+    {
+      name: 'get_document_metadata',
+      description: "Fetch a document's metadata",
+      inputSchema: {
+        type: 'object',
+        properties: {
+          document_id: {
+            type: 'string',
+            description: 'The document ID'
+          }
+        },
+        required: ['document_id']
+      }
+    },
+    {
+      name: 'get_document_content',
+      description: 'Fetch a document content (PDF)',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          document_id: {
+            type: 'string',
+            description: 'The document ID'
+          }
+        },
+        required: ['document_id']
+      }
+    }
+  ];
+}
+
 export function getAllTools(): Tool[] {
   return [
     ...getCompanyTools(),
     ...getSearchTools(),
     ...getOfficersTools(),
     ...getFilingTools(),
     ...getChargesTools(),
-    ...getPSCTools()
+    ...getPSCTools(),
+    ...getDocumentTools()
   ];
 }

src/types/document.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+
+export const DocumentMetadataSchema = z.object({
+  document_id: z.string().min(1).describe('The document ID')
+});
+
+export const DocumentContentSchema = z.object({
+  document_id: z.string().min(1).describe('The document ID')
+});
+
+export const DocumentMetadataResponseSchema = z.object({
+  company_number: z.string().optional(),
+  barcode: z.string().optional(),
+  significant_date: z.string().optional(),
+  significant_date_type: z.string().optional(),
+  category: z.string().optional(),
+  pages: z.number().optional(),
+  filename: z.string().optional(),
+  created_at: z.string().optional(),
+  updated_at: z.string().optional(),
+  etag: z.string().optional(),
+  links: z
+    .object({
+      self: z.string().optional(),
+      document: z.string().optional()
+    })
+    .optional(),
+  resources: z
+    .record(
+      z.object({
+        content_length: z.number().optional(),
+        content_type: z.string().optional(),
+        created_at: z.string().optional(),
+        updated_at: z.string().optional()
+      })
+    )
+    .optional()
+});
+
+export type DocumentMetadata = z.infer<typeof DocumentMetadataSchema>;
+export type DocumentContent = z.infer<typeof DocumentContentSchema>;
+export type DocumentMetadataResponse = z.infer<typeof DocumentMetadataResponseSchema>;

src/types/index.ts

@@ -6,3 +6,4 @@ export * from './charges.js';
 export * from './psc.js';
 export * from './psc-response.js';
 export * from './search-response.js';
+export * from './document.js';

tests/document-api.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import axios, { AxiosInstance } from 'axios';
+import { DocumentApiClient } from '../src/api/document-api';
+
+vi.mock('axios');
+
+describe('DocumentApiClient', () => {
+  let apiClient: DocumentApiClient;
+  let mockAxiosInstance: Partial<AxiosInstance>;
+
+  beforeEach(() => {
+    mockAxiosInstance = {
+      get: vi.fn(),
+      interceptors: {
+        response: {
+          use: vi.fn()
+        }
+      }
+    };
+
+    (axios.create as ReturnType<typeof vi.fn>).mockReturnValue(mockAxiosInstance as AxiosInstance);
+
+    apiClient = new DocumentApiClient({
+      apiKey: 'test-api-key'
+    });
+  });
+
+  describe('getDocumentMetadata', () => {
+    it('should fetch document metadata', async () => {
+      const mockResponse = {
+        data: {
+          company_number: '12345678',
+          barcode: 'ABC123',
+          category: 'accounts',
+          pages: 10,
+          filename: 'document.pdf',
+          links: {
+            self: '/document/doc123',
+            document: '/document/doc123/content'
+          }
+        }
+      };
+
+      (mockAxiosInstance.get as ReturnType<typeof vi.fn>).mockResolvedValue(mockResponse);
+
+      const result = await apiClient.getDocumentMetadata({ document_id: 'doc123' });
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/document/doc123');
+      expect(result).toEqual(mockResponse.data);
+    });
+
+    it('should handle errors when fetching metadata', async () => {
+      const error = new Error('API Error');
+      (mockAxiosInstance.get as ReturnType<typeof vi.fn>).mockRejectedValue(error);
+
+      await expect(apiClient.getDocumentMetadata({ document_id: 'doc123' })).rejects.toThrow(
+        'API Error'
+      );
+    });
+  });
+
+  describe('getDocumentContent', () => {
+    it('should fetch document content as buffer', async () => {
+      const mockPdfData = new ArrayBuffer(1024);
+      const mockResponse = {
+        data: mockPdfData
+      };
+
+      (mockAxiosInstance.get as ReturnType<typeof vi.fn>).mockResolvedValue(mockResponse);
+
+      const result = await apiClient.getDocumentContent({ document_id: 'doc123' });
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/document/doc123/content', {
+        responseType: 'arraybuffer',
+        headers: {
+          Accept: 'application/pdf'
+        }
+      });
+      expect(result).toBeInstanceOf(Buffer);
+      expect(result.length).toBe(1024);
+    });
+
+    it('should handle errors when fetching content', async () => {
+      const error = new Error('Failed to fetch document');
+      (mockAxiosInstance.get as ReturnType<typeof vi.fn>).mockRejectedValue(error);
+
+      await expect(apiClient.getDocumentContent({ document_id: 'doc123' })).rejects.toThrow(
+        'Failed to fetch document'
+      );
+    });
+  });
+});