@access-mcp/shared 0.2.0

package/README.md

@@ -0,0 +1,43 @@
+# @access-mcp/shared
+
+Shared utilities and base classes for ACCESS-CI MCP servers.
+
+## Overview
+
+This package provides the common infrastructure used by all ACCESS-CI MCP servers:
+
+- **BaseAccessServer**: Abstract base class for creating MCP servers
+- **Error handling utilities**: Consistent error handling across servers
+- **Type definitions**: Shared TypeScript types
+- **API utilities**: Helper functions for API interactions
+
+## Installation
+
+```bash
+npm install @access-mcp/shared
+```
+
+## Usage
+
+```typescript
+import { BaseAccessServer, handleApiError } from '@access-mcp/shared';
+
+export class MyServer extends BaseAccessServer {
+  constructor() {
+    super('my-server', '1.0.0');
+  }
+  
+  // Implement required abstract methods
+}
+```
+
+## Features
+
+- Automatic stdio transport setup
+- Consistent error handling
+- Built-in axios HTTP client with authentication support
+- TypeScript support with full type definitions
+
+## License
+
+MIT

package/dist/__tests__/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/utils.test.js

@@ -0,0 +1,50 @@
+import { describe, test, expect } from 'vitest';
+import { sanitizeGroupId, formatApiUrl, handleApiError } from '../utils.js';
+describe('Utils', () => {
+    describe('sanitizeGroupId', () => {
+        test('should remove invalid characters', () => {
+            expect(sanitizeGroupId('test@#$%')).toBe('test');
+        });
+        test('should keep valid characters', () => {
+            expect(sanitizeGroupId('test.group-123')).toBe('test.group-123');
+        });
+        test('should handle empty string', () => {
+            expect(sanitizeGroupId('')).toBe('');
+        });
+    });
+    describe('formatApiUrl', () => {
+        test('should format API URL correctly', () => {
+            expect(formatApiUrl('1.0', 'users')).toBe('/1.0/users');
+        });
+        test('should handle empty endpoint', () => {
+            expect(formatApiUrl('2.0', '')).toBe('/2.0/');
+        });
+    });
+    describe('handleApiError', () => {
+        test('should extract message from response data', () => {
+            const error = {
+                response: {
+                    data: { message: 'Custom error message' }
+                }
+            };
+            expect(handleApiError(error)).toBe('Custom error message');
+        });
+        test('should handle status error', () => {
+            const error = {
+                response: {
+                    status: 404,
+                    statusText: 'Not Found'
+                }
+            };
+            expect(handleApiError(error)).toBe('API error: 404 Not Found');
+        });
+        test('should handle error message', () => {
+            const error = { message: 'Network error' };
+            expect(handleApiError(error)).toBe('Network error');
+        });
+        test('should handle unknown error', () => {
+            const error = {};
+            expect(handleApiError(error)).toBe('Unknown API error');
+        });
+    });
+});

package/dist/base-server.d.ts

@@ -0,0 +1,19 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { AxiosInstance } from 'axios';
+export declare abstract class BaseAccessServer {
+    protected serverName: string;
+    protected version: string;
+    protected baseURL: string;
+    protected server: Server;
+    protected transport: StdioServerTransport;
+    private _httpClient?;
+    constructor(serverName: string, version: string, baseURL?: string);
+    protected get httpClient(): AxiosInstance;
+    private setupHandlers;
+    protected abstract getTools(): any[];
+    protected abstract getResources(): any[];
+    protected abstract handleToolCall(request: any): Promise<any>;
+    protected abstract handleResourceRead(request: any): Promise<any>;
+    start(): Promise<void>;
+}

package/dist/base-server.js

@@ -0,0 +1,107 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import axios from 'axios';
+export class BaseAccessServer {
+    serverName;
+    version;
+    baseURL;
+    server;
+    transport;
+    _httpClient;
+    constructor(serverName, version, baseURL = 'https://support.access-ci.org/api') {
+        this.serverName = serverName;
+        this.version = version;
+        this.baseURL = baseURL;
+        this.server = new Server({
+            name: serverName,
+            version: version,
+        }, {
+            capabilities: {
+                resources: {},
+                tools: {},
+            },
+        });
+        this.transport = new StdioServerTransport();
+        this.setupHandlers();
+    }
+    get httpClient() {
+        if (!this._httpClient) {
+            const headers = {
+                'User-Agent': `${this.serverName}/${this.version}`,
+            };
+            // Add authentication if API key is provided
+            const apiKey = process.env.ACCESS_CI_API_KEY;
+            if (apiKey) {
+                headers['Authorization'] = `Bearer ${apiKey}`;
+            }
+            this._httpClient = axios.create({
+                baseURL: this.baseURL,
+                timeout: 5000,
+                headers,
+                validateStatus: () => true, // Don't throw on HTTP errors
+            });
+        }
+        return this._httpClient;
+    }
+    setupHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            try {
+                return { tools: this.getTools() };
+            }
+            catch (error) {
+                // Silent error handling for MCP compatibility
+                return { tools: [] };
+            }
+        });
+        this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+            try {
+                return { resources: this.getResources() };
+            }
+            catch (error) {
+                // Silent error handling for MCP compatibility
+                return { resources: [] };
+            }
+        });
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            try {
+                return await this.handleToolCall(request);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error('Error handling tool call:', errorMessage);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${errorMessage}`,
+                        },
+                    ],
+                };
+            }
+        });
+        this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+            try {
+                return await this.handleResourceRead(request);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error('Error reading resource:', errorMessage);
+                return {
+                    contents: [
+                        {
+                            uri: request.params.uri,
+                            mimeType: 'text/plain',
+                            text: `Error: ${errorMessage}`,
+                        },
+                    ],
+                };
+            }
+        });
+    }
+    async start() {
+        await this.server.connect(this.transport);
+        // MCP servers should not output anything to stderr/stdout when running
+        // as it interferes with JSON-RPC communication
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './base-server';
+export * from './types';
+export * from './utils';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './base-server';
+export * from './types';
+export * from './utils';

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+export declare const AffinityGroupSchema: z.ZodObject<{
+    group_id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    group_id: string;
+    name?: string | undefined;
+    description?: string | undefined;
+}, {
+    group_id: string;
+    name?: string | undefined;
+    description?: string | undefined;
+}>;
+export declare const EventSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    start_date: z.ZodOptional<z.ZodString>;
+    end_date: z.ZodOptional<z.ZodString>;
+    location: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    id: string;
+    description?: string | undefined;
+    start_date?: string | undefined;
+    end_date?: string | undefined;
+    location?: string | undefined;
+}, {
+    title: string;
+    id: string;
+    description?: string | undefined;
+    start_date?: string | undefined;
+    end_date?: string | undefined;
+    location?: string | undefined;
+}>;
+export declare const KnowledgeBaseResourceSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    content: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    id: string;
+    content?: string | undefined;
+    category?: string | undefined;
+    tags?: string[] | undefined;
+}, {
+    title: string;
+    id: string;
+    content?: string | undefined;
+    category?: string | undefined;
+    tags?: string[] | undefined;
+}>;
+export type AffinityGroup = z.infer<typeof AffinityGroupSchema>;
+export type Event = z.infer<typeof EventSchema>;
+export type KnowledgeBaseResource = z.infer<typeof KnowledgeBaseResourceSchema>;

package/dist/types.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export const AffinityGroupSchema = z.object({
+    group_id: z.string(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+});
+export const EventSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    description: z.string().optional(),
+    start_date: z.string().optional(),
+    end_date: z.string().optional(),
+    location: z.string().optional(),
+});
+export const KnowledgeBaseResourceSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    content: z.string().optional(),
+    category: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+});

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+export declare function sanitizeGroupId(groupId: string): string;
+export declare function formatApiUrl(version: string, endpoint: string): string;
+export declare function handleApiError(error: any): string;

package/dist/utils.js

@@ -0,0 +1,15 @@
+export function sanitizeGroupId(groupId) {
+    return groupId.replace(/[^a-zA-Z0-9.-]/g, '');
+}
+export function formatApiUrl(version, endpoint) {
+    return `/${version}/${endpoint}`;
+}
+export function handleApiError(error) {
+    if (error.response?.data?.message) {
+        return error.response.data.message;
+    }
+    if (error.response?.status) {
+        return `API error: ${error.response.status} ${error.response.statusText}`;
+    }
+    return error.message || 'Unknown API error';
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@access-mcp/shared",
+  "version": "0.2.0",
+  "description": "Shared utilities for ACCESS-CI MCP servers",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "access-ci",
+    "hpc",
+    "utilities"
+  ],
+  "author": "ACCESS-CI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/access-ci/access-mcp.git",
+    "directory": "packages/shared"
+  },
+  "homepage": "https://github.com/access-ci/access-mcp#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.16.0",
+    "axios": "^1.6.0",
+    "zod": "^3.22.0"
+  }
+}