Pluggable DevelopersApi and OAuth 2.0 tool (#48)

* Add injectable DevelopersApi support and OAuth 2.0 tool

* Simplify tool signatures: move client into `ToolContext`

* Update test cases to include client context in execute function

Author: ech0s7r

README.md

@@ -28,6 +28,7 @@ The toolkit provides the following tools for agents to use:
 * `get-documentation-section-content`: Retrieves the complete content for a specific documentation section.
 * `get-documentation-page`: Retrieves the complete content of a specific documentation page.
 * `get-oauth10a-integration-guide`: Retrieves the comprehensive OAuth 1.0a integration guide.
+* `get-oauth20-integration-guide`: Retrieves the comprehensive OAuth 2.0 integration guide.
 * `get-openfinance-integration-guide`: Retrieves the comprehensive Open Finance integration guide.
 
 ### API Operations

modelcontextprotocol/README.md

@@ -14,7 +14,7 @@ This MCP server acts as a bridge between MCP clients and Mastercard Developers r
 - List available Mastercard services
 - Query API specifications and their operations
 - Access documentation for each service
-- Retrieve integration guides for OAuth 1.0a and Open Finance
+- Retrieve integration guides for OAuth 1.0a, OAuth 2.0, and Open Finance
 
 ## Available Tools
 
@@ -40,6 +40,8 @@ This MCP server acts as a bridge between MCP clients and Mastercard Developers r
 
 - **`get-oauth10a-integration-guide`**: Retrieves the comprehensive OAuth 1.0a integration guide including step-by-step instructions, code examples, and best practices for Mastercard APIs.
 
+- **`get-oauth20-integration-guide`**: Retrieves the comprehensive OAuth 2.0 integration guide including step-by-step instructions, code examples, and best practices for Mastercard APIs.
+
 - **`get-openfinance-integration-guide`**: Retrieves the comprehensive Open Finance integration guide including setup instructions, API usage examples, and implementation best practices.
 
 ## Configuration Options

typescript/package-lock.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.4",
+  "version": "0.1.5",
   "name": "@mastercard/developers-agent-toolkit",
   "homepage": "https://github.com/mastercard/developers-agent-toolkit",
   "description": "Agent Toolkit for Mastercard Developers Platform",

typescript/package.json

@@ -38,7 +38,7 @@ describe('MastercardDevelopersAgentToolkit', () => {
 
   it('should list all tools with correct name/description when no config', async () => {
     const registeredTools = await listRegisteredTools({});
-    const expectedTools = tools({});
+    const expectedTools = tools(buildContext({}));
     expect(registeredTools).toHaveLength(expectedTools.length);
 
     expectedTools.forEach((expectedTool, index) => {
@@ -60,10 +60,12 @@ describe('MastercardDevelopersAgentToolkit', () => {
         'https://static.developer.mastercard.com/content/service/swagger/path.yaml',
     });
 
-    const expectedTools = tools({
-      serviceId: 'service',
-      apiSpecificationPath: '/service/swagger/path.yaml',
-    }).filter((tool) => tool.name !== 'get-services-list');
+    const expectedTools = tools(
+      buildContext({
+        apiSpecification:
+          'https://static.developer.mastercard.com/content/service/swagger/path.yaml',
+      })
+    ).filter((tool) => tool.name !== 'get-services-list');
     expect(registeredTools).toHaveLength(expectedTools.length);
 
     expectedTools.forEach((expectedTool, index) => {
@@ -84,9 +86,11 @@ describe('MastercardDevelopersAgentToolkit', () => {
       service: 'https://developer.mastercard.com/test-service/documentation/',
     });
 
-    const expectedTools = tools({ serviceId: 'test-service' }).filter(
-      (tool) => tool.name !== 'get-services-list'
-    );
+    const expectedTools = tools(
+      buildContext({
+        service: 'https://developer.mastercard.com/test-service/documentation/',
+      })
+    ).filter((tool) => tool.name !== 'get-services-list');
     const registeredNames = registeredTools.map((tool) => tool.name);
 
     expect(registeredNames).not.toContain('get-services-list');
@@ -110,49 +114,57 @@ describe('buildContext function', () => {
   describe('success cases', () => {
     it('should return empty context when no config provided', () => {
       const result = buildContext({});
-      expect(result).toEqual({});
+      expect(result).toEqual(expect.objectContaining({}));
     });
 
     it('should parse service URL and extract serviceId', () => {
       const result = buildContext({
         service:
           'https://developer.mastercard.com/open-finance-us/documentation/',
       });
-      expect(result).toEqual({
-        serviceId: 'open-finance-us',
-      });
+      expect(result).toEqual(
+        expect.objectContaining({
+          serviceId: 'open-finance-us',
+        })
+      );
     });
 
     it('should parse API specification URL and extract serviceId and apiSpecificationPath', () => {
       const result = buildContext({
         apiSpecification:
           'https://static.developer.mastercard.com/content/test-service/swagger/api.yaml',
       });
-      expect(result).toEqual({
-        serviceId: 'test-service',
-        apiSpecificationPath: '/test-service/swagger/api.yaml',
-      });
+      expect(result).toEqual(
+        expect.objectContaining({
+          serviceId: 'test-service',
+          apiSpecificationPath: '/test-service/swagger/api.yaml',
+        })
+      );
     });
 
     it('should handle nested API specification paths', () => {
       const result = buildContext({
         apiSpecification:
           'https://static.developer.mastercard.com/content/payment-gateway/swagger/nested/spec.yaml',
       });
-      expect(result).toEqual({
-        serviceId: 'payment-gateway',
-        apiSpecificationPath: '/payment-gateway/swagger/nested/spec.yaml',
-      });
+      expect(result).toEqual(
+        expect.objectContaining({
+          serviceId: 'payment-gateway',
+          apiSpecificationPath: '/payment-gateway/swagger/nested/spec.yaml',
+        })
+      );
     });
 
     it('should handle service IDs with hyphens and numbers', () => {
       const result = buildContext({
         service:
           'https://developer.mastercard.com/open-finance-us-v2/documentation/',
       });
-      expect(result).toEqual({
-        serviceId: 'open-finance-us-v2',
-      });
+      expect(result).toEqual(
+        expect.objectContaining({
+          serviceId: 'open-finance-us-v2',
+        })
+      );
     });
   });
 

typescript/src/modelcontextprotocol/__tests__/index.test.ts

@@ -1,8 +1,12 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { defaultDevelopersApi } from '@/shared/api';
 import { tools } from '@/shared/tools';
 import { ToolContext } from '@/shared/types';
 import { version } from '../../package.json';
 
+export type { DevelopersApi, Tool, ToolContext } from '@/shared/types';
+export { tools } from '@/shared/tools';
+
 export interface MastercardDevelopersAgentToolkitConfig {
   service?: string;
   apiSpecification?: string;
@@ -61,7 +65,7 @@ export class MastercardDevelopersAgentToolkit extends McpServer {
 export function buildContext(
   config: MastercardDevelopersAgentToolkitConfig
 ): ToolContext {
-  const context: ToolContext = {};
+  const context: ToolContext = { client: defaultDevelopersApi };
   if (config.service != null) {
     const serviceId = parseServiceIdFromUrl(config.service);
     if (serviceId == null) {

typescript/src/modelcontextprotocol/index.ts

@@ -1,4 +1,4 @@
-import { MastercardAPIClient } from '@/shared/api';
+import { defaultDevelopersApi, MastercardAPIClient } from '@/shared/api';
 import fetch, { RequestInfo, Response } from 'node-fetch';
 
 const mcd = (path: string) => {
@@ -8,6 +8,12 @@ const mcd = (path: string) => {
 const mockFetch = fetch as jest.MockedFunction<typeof fetch>;
 jest.mock('node-fetch');
 
+describe('defaultDevelopersApi', () => {
+  it('uses the default MastercardAPIClient implementation', () => {
+    expect(defaultDevelopersApi).toBeInstanceOf(MastercardAPIClient);
+  });
+});
+
 describe('MastercardAPIClient', () => {
   let client: MastercardAPIClient;
 

typescript/src/shared/api/__tests__/index.test.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import fetch from 'node-fetch';
 
+import type { DevelopersApi } from '@/shared/types';
+
 const PathSchema = z
   .string()
   .min(1, 'Path must be a non-empty string')
@@ -106,5 +108,4 @@ export class MastercardAPIClient {
   }
 }
 
-const api = new MastercardAPIClient();
-export default api;
+export const defaultDevelopersApi: DevelopersApi = new MastercardAPIClient();

typescript/src/shared/api/index.ts

@@ -2,11 +2,9 @@ import {
   execute,
   getParameters,
 } from '@/shared/tools/documentation/getDocumentation';
-import api from '@/shared/api';
+import { createMockApi } from '@/tests/mockDevelopersApi';
 
-jest.mock<typeof api>('@/shared/api');
-
-const mockApi = api as jest.Mocked<typeof api>;
+const mockApi = createMockApi();
 
 describe('execute', () => {
   beforeEach(() => {
@@ -17,7 +15,10 @@ describe('execute', () => {
     const mockResult = 'mock documentation';
     mockApi.getDocumentation.mockResolvedValue(mockResult);
 
-    const result = await execute({}, { serviceId: 'test-service' });
+    const result = await execute(
+      { client: mockApi },
+      { serviceId: 'test-service' }
+    );
 
     expect(mockApi.getDocumentation).toHaveBeenCalledWith('test-service');
     expect(result).toBe(mockResult);
@@ -27,7 +28,10 @@ describe('execute', () => {
     const mockResult = 'mock documentation';
     mockApi.getDocumentation.mockResolvedValue(mockResult);
 
-    const result = await execute({ serviceId: 'context-service' }, {});
+    const result = await execute(
+      { client: mockApi, serviceId: 'context-service' },
+      {}
+    );
 
     expect(mockApi.getDocumentation).toHaveBeenCalledWith('context-service');
     expect(result).toBe(mockResult);
@@ -36,15 +40,18 @@ describe('execute', () => {
 
 describe('getParameters', () => {
   it('should return the correct parameters if no context', () => {
-    const parameters = getParameters({});
+    const parameters = getParameters({ client: mockApi });
 
     const fields = Object.keys(parameters.shape);
     expect(fields).toEqual(['serviceId']);
     expect(fields.length).toBe(1);
   });
 
   it('should return the correct parameters if serviceId is specified in context', () => {
-    const parameters = getParameters({ serviceId: 'test-service' });
+    const parameters = getParameters({
+      client: mockApi,
+      serviceId: 'test-service',
+    });
 
     const fields = Object.keys(parameters.shape);
     expect(fields).toEqual([]);

typescript/src/shared/tools/documentation/__tests__/getDocumentation.test.ts

@@ -2,11 +2,9 @@ import {
   execute,
   getParameters,
 } from '@/shared/tools/documentation/getDocumentationPage';
-import api from '@/shared/api';
+import { createMockApi } from '@/tests/mockDevelopersApi';
 
-jest.mock<typeof api>('@/shared/api');
-
-const mockApi = api as jest.Mocked<typeof api>;
+const mockApi = createMockApi();
 
 describe('execute', () => {
   beforeEach(() => {
@@ -17,7 +15,10 @@ describe('execute', () => {
     const mockResult = 'mock documentation page content';
     mockApi.getDocumentationPage.mockResolvedValue(mockResult);
 
-    const result = await execute({}, { pagePath: '/test/page.md' });
+    const result = await execute(
+      { client: mockApi },
+      { pagePath: '/test/page.md' }
+    );
 
     expect(mockApi.getDocumentationPage).toHaveBeenCalledWith('/test/page.md');
     expect(result).toBe(mockResult);
@@ -26,7 +27,7 @@ describe('execute', () => {
 
 describe('getParameters', () => {
   it('should return the correct parameters if no context', () => {
-    const parameters = getParameters({});
+    const parameters = getParameters({ client: mockApi });
 
     const fields = Object.keys(parameters.shape);
     expect(fields).toEqual(['pagePath']);