@access-mcp/announcements 0.1.0

package/dist/server.js

@@ -0,0 +1,307 @@
+import { BaseAccessServer } from "@access-mcp/shared";
+export class AnnouncementsServer extends BaseAccessServer {
+    constructor() {
+        super("access-announcements", "0.1.0", "https://support.access-ci.org");
+    }
+    getTools() {
+        return [
+            {
+                name: "get_announcements",
+                description: "Search ACCESS support announcements about system maintenance, service updates, outages, and community news. Use this when users ask about recent announcements, service status, or need to filter by dates, tags, or affinity groups.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        tags: {
+                            type: "string",
+                            description: "Filter by specific topics (comma-separated). Real examples: 'gpu,nvidia', 'machine-learning,ai', 'maintenance,downtime', 'training,workshop', 'allocation-users', 'data-science', 'cloud-computing', 'bridges-2,anvil'"
+                        },
+                        ag: {
+                            type: "string",
+                            description: "Filter by system/community affinity group. Real examples: 'ACCESS Support', 'DELTA', 'Anvil', 'Bridges-2', 'CSSN (Computational Science Support Network)', 'Open OnDemand', 'Pegasus'"
+                        },
+                        affiliation: {
+                            type: "string",
+                            description: "Filter by organization affiliation (e.g., 'ACCESS')"
+                        },
+                        relative_start_date: {
+                            type: "string",
+                            description: "Filter announcements from a relative date. Examples: 'today', '-1 week', '-1 month', '-3 months', '-1 year'. Use negative values for past dates"
+                        },
+                        relative_end_date: {
+                            type: "string",
+                            description: "Filter announcements up to a relative date. Examples: 'now', 'today', '-1 week' (past), '+1 week' (future)"
+                        },
+                        start_date: {
+                            type: "string",
+                            description: "Filter announcements from exact date onwards (YYYY-MM-DD). Use when users specify dates like 'since January 1st, 2024' or 'from March 15th'"
+                        },
+                        end_date: {
+                            type: "string",
+                            description: "Filter announcements up to exact date (YYYY-MM-DD). Use when users specify dates like 'until December 31st, 2024' or 'before April 1st'"
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Maximum number of announcements to return. Use smaller values (5-10) for quick overviews, larger values (20-50) for comprehensive searches",
+                            default: 20
+                        }
+                    }
+                }
+            },
+            {
+                name: "get_announcements_by_tags",
+                description: "Find announcements about specific topics or systems. Use when users ask about particular subjects like 'GPU maintenance', 'machine learning resources', 'training workshops', or 'cloud computing updates'.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        tags: {
+                            type: "string",
+                            description: "Specific topics to search for (comma-separated). Popular examples: 'gpu,nvidia', 'machine-learning,ai', 'training,professional-development', 'data-science,python', 'cloud-computing', 'allocations-proposal'",
+                            required: true
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Maximum number of announcements to return",
+                            default: 10
+                        }
+                    },
+                    required: ["tags"]
+                }
+            },
+            {
+                name: "get_announcements_by_affinity_group",
+                description: "Get announcements for a specific ACCESS system or community group. Use when users ask about updates for particular resources like DELTA, Anvil, or Bridges-2, or community groups like CSSN.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        ag: {
+                            type: "string",
+                            description: "The system or community group name (not the technical API ID). Examples: 'DELTA', 'Anvil', 'Bridges-2', 'ACCESS Support', 'Open OnDemand', 'Pegasus', 'CSSN (Computational Science Support Network)'",
+                            required: true
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Maximum number of announcements to return",
+                            default: 10
+                        }
+                    },
+                    required: ["ag"]
+                }
+            },
+            {
+                name: "get_recent_announcements",
+                description: "Get the latest ACCESS support announcements from a recent time period. Use this when users ask 'what's new?', 'recent updates', 'latest announcements', or want a general overview of current activity.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        period: {
+                            type: "string",
+                            description: "How far back to look for announcements. Examples: '1 week', '2 weeks', '1 month', '3 months', '6 months'. Default is '1 month'",
+                            default: "1 month"
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Maximum number of announcements to return",
+                            default: 10
+                        }
+                    }
+                }
+            }
+        ];
+    }
+    getResources() {
+        return [
+            {
+                uri: "accessci://announcements",
+                name: "ACCESS Support Announcements",
+                description: "Recent announcements and notifications from ACCESS support",
+                mimeType: "application/json"
+            }
+        ];
+    }
+    async handleToolCall(request) {
+        const { name, arguments: args } = request.params;
+        try {
+            switch (name) {
+                case "get_announcements":
+                    return await this.getAnnouncements(args);
+                case "get_announcements_by_tags":
+                    return await this.getAnnouncementsByTags(args.tags, args.limit);
+                case "get_announcements_by_affinity_group":
+                    return await this.getAnnouncementsByAffinityGroup(args.ag, args.limit);
+                case "get_recent_announcements":
+                    return await this.getRecentAnnouncements(args.period, args.limit);
+                default:
+                    throw new Error(`Unknown tool: ${name}`);
+            }
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error.message}`
+                    }
+                ]
+            };
+        }
+    }
+    async handleResourceRead(request) {
+        const { uri } = request.params;
+        if (uri === "accessci://announcements") {
+            try {
+                const announcements = await this.fetchAnnouncements({ limit: 10 });
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: "application/json",
+                            text: JSON.stringify(announcements, null, 2)
+                        }
+                    ]
+                };
+            }
+            catch (error) {
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: "text/plain",
+                            text: `Error loading announcements: ${error.message}`
+                        }
+                    ]
+                };
+            }
+        }
+        throw new Error(`Unknown resource: ${uri}`);
+    }
+    buildAnnouncementsUrl(filters) {
+        const params = new URLSearchParams();
+        if (filters.tags) {
+            params.append("tags", filters.tags);
+        }
+        if (filters.ag) {
+            params.append("ag", filters.ag);
+        }
+        if (filters.affiliation) {
+            params.append("affiliation", filters.affiliation);
+        }
+        if (filters.relative_start_date) {
+            params.append("relative_start_date", filters.relative_start_date);
+        }
+        if (filters.relative_end_date) {
+            params.append("relative_end_date", filters.relative_end_date);
+        }
+        if (filters.start_date) {
+            params.append("start_date", filters.start_date);
+        }
+        if (filters.end_date) {
+            params.append("end_date", filters.end_date);
+        }
+        return `/api/2.1/announcements?${params.toString()}`;
+    }
+    async fetchAnnouncements(filters) {
+        const url = this.buildAnnouncementsUrl(filters);
+        const response = await this.httpClient.get(url);
+        if (response.status !== 200) {
+            throw new Error(`API Error ${response.status}: ${response.statusText}`);
+        }
+        const announcements = response.data || [];
+        return this.enhanceAnnouncements(announcements);
+    }
+    enhanceAnnouncements(rawAnnouncements) {
+        return rawAnnouncements.map(announcement => ({
+            ...announcement,
+            date: announcement.field_published_date,
+            tags: announcement.custom_announcement_tags
+                ? announcement.custom_announcement_tags.split(',').map((t) => t.trim()).filter((t) => t)
+                : [],
+            formatted_date: announcement.field_published_date
+                ? new Date(announcement.field_published_date).toLocaleDateString('en-US', {
+                    year: 'numeric',
+                    month: 'long',
+                    day: 'numeric'
+                })
+                : '',
+            body_preview: announcement.body
+                ? announcement.body.replace(/<[^>]*>/g, '').substring(0, 200) + '...'
+                : '',
+            affinity_groups: announcement.custom_announcement_ag
+                ? announcement.custom_announcement_ag.split(',').map((g) => g.trim()).filter((g) => g)
+                : []
+        }));
+    }
+    async getAnnouncements(filters) {
+        const announcements = await this.fetchAnnouncements(filters);
+        const limited = filters.limit ? announcements.slice(0, filters.limit) : announcements;
+        // Build filters_applied object
+        const filters_applied = {};
+        if (filters.tags)
+            filters_applied.tags = filters.tags;
+        if (filters.ag)
+            filters_applied.affinity_group = filters.ag;
+        if (filters.relative_start_date || filters.relative_end_date) {
+            filters_applied.date_range = `${filters.relative_start_date || 'any'} to ${filters.relative_end_date || 'now'}`;
+        }
+        if (filters.start_date || filters.end_date) {
+            filters_applied.date_range = `${filters.start_date || 'any'} to ${filters.end_date || 'now'}`;
+        }
+        if (filters.limit)
+            filters_applied.limit = filters.limit;
+        const result = {
+            total_announcements: announcements.length,
+            filtered_announcements: limited.length,
+            announcements: limited,
+            filters_applied,
+            popular_tags: this.getPopularTags(limited),
+            message: limited.length === 0 ? "No announcements found matching the filters" : undefined
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }
+            ]
+        };
+    }
+    async getAnnouncementsByTags(tags, limit = 10) {
+        return await this.getAnnouncements({ tags, limit });
+    }
+    async getAnnouncementsByAffinityGroup(ag, limit = 10) {
+        return await this.getAnnouncements({ ag, limit });
+    }
+    async getRecentAnnouncements(period = "1 month", limit = 10) {
+        const relativeStart = `-${period}`;
+        return await this.getAnnouncements({
+            relative_start_date: relativeStart,
+            relative_end_date: "now",
+            limit
+        });
+    }
+    getPopularTags(announcements) {
+        const tagCounts = {};
+        announcements.forEach(announcement => {
+            if (announcement.tags) {
+                announcement.tags.forEach((tag) => {
+                    tagCounts[tag] = (tagCounts[tag] || 0) + 1;
+                });
+            }
+        });
+        return Object.entries(tagCounts)
+            .sort(([, a], [, b]) => b - a)
+            .slice(0, 10)
+            .map(([tag]) => tag);
+    }
+    getAffinityGroups(announcements) {
+        const groups = new Set();
+        announcements.forEach(announcement => {
+            if (announcement.affinity_groups && Array.isArray(announcement.affinity_groups)) {
+                announcement.affinity_groups.forEach((group) => {
+                    if (group)
+                        groups.add(group);
+                });
+            }
+        });
+        return Array.from(groups);
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@access-mcp/announcements",
+  "version": "0.1.0",
+  "description": "MCP server for ACCESS Support Announcements API",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "access-mcp-announcements": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:all": "vitest run && vitest run --config vitest.integration.config.ts",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "mcp",
+    "access-ci",
+    "announcements",
+    "support"
+  ],
+  "author": "ACCESS-CI",
+  "license": "MIT",
+  "dependencies": {
+    "@access-mcp/shared": "file:../shared",
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "axios": "^1.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { AnnouncementsServer } from "./server.js";
+
+async function main() {
+  // Check if we should run as HTTP server (for deployment)
+  const port = process.env.PORT;
+
+  const server = new AnnouncementsServer();
+  
+  if (port) {
+    // Running in HTTP mode (deployment)
+    await server.start({ httpPort: parseInt(port) });
+    // Keep the process running in HTTP mode
+    process.on('SIGINT', () => {
+      console.log('Shutting down server...');
+      process.exit(0);
+    });
+    // Keep the event loop alive
+    setInterval(() => {}, 1000 * 60 * 60); // Heartbeat every hour
+  } else {
+    // Running in MCP mode (stdio)
+    await server.start();
+  }
+}
+
+main().catch((error) => {
+  // Log errors to stderr and exit
+  console.error("Server error:", error);
+  process.exit(1);
+});

package/src/server.integration.test.ts

@@ -0,0 +1,220 @@
+import { describe, it, expect } from "vitest";
+import { AnnouncementsServer } from "./server.js";
+
+/**
+ * Integration tests for AnnouncementsServer
+ * These tests make actual API calls to the ACCESS Support API
+ */
+describe("AnnouncementsServer Integration Tests", () => {
+  let server: AnnouncementsServer;
+
+  beforeEach(() => {
+    server = new AnnouncementsServer();
+  });
+
+  describe("get_announcements", () => {
+    it("should fetch real announcements from API", async () => {
+      const result = await server["handleToolCall"]({
+        params: {
+          name: "get_announcements",
+          arguments: {
+            limit: 5,
+          },
+        },
+      } as any);
+
+      expect(result.isError).toBeFalsy();
+      const responseData = JSON.parse(result.content[0].text);
+      
+      // Check structure
+      expect(responseData).toHaveProperty("total_announcements");
+      expect(responseData).toHaveProperty("announcements");
+      expect(responseData).toHaveProperty("popular_tags");
+      expect(responseData).toHaveProperty("filters_applied");
+      
+      // Announcements should be an array
+      expect(Array.isArray(responseData.announcements)).toBe(true);
+      
+      // If there are announcements, check their structure
+      if (responseData.announcements.length > 0) {
+        const firstAnnouncement = responseData.announcements[0];
+        expect(firstAnnouncement).toHaveProperty("title");
+        expect(firstAnnouncement).toHaveProperty("body");
+        expect(firstAnnouncement).toHaveProperty("date");
+        expect(firstAnnouncement).toHaveProperty("formatted_date");
+        expect(firstAnnouncement).toHaveProperty("tags");
+        expect(Array.isArray(firstAnnouncement.tags)).toBe(true);
+      }
+    }, 10000);
+
+    it("should filter by tags", async () => {
+      const result = await server["handleToolCall"]({
+        params: {
+          name: "get_announcements_by_tags",
+          arguments: {
+            tags: "maintenance",
+            limit: 3,
+          },
+        },
+      } as any);
+
+      expect(result.isError).toBeFalsy();
+      const responseData = JSON.parse(result.content[0].text);
+      
+      expect(responseData).toHaveProperty("announcements");
+      expect(Array.isArray(responseData.announcements)).toBe(true);
+      
+      // If maintenance announcements exist, they should contain the tag
+      if (responseData.announcements.length > 0) {
+        const hasMaintenanceTag = responseData.announcements.some((ann: any) => 
+          ann.tags && ann.tags.some((tag: string) => 
+            tag.toLowerCase().includes("maintenance")
+          )
+        );
+        // This might not always be true if the API doesn't have maintenance announcements
+        console.log("Found maintenance announcements:", hasMaintenanceTag);
+      }
+    }, 10000);
+
+    it("should handle date range filters", async () => {
+      const result = await server["handleToolCall"]({
+        params: {
+          name: "get_announcements",
+          arguments: {
+            relative_start_date: "-1month",
+            relative_end_date: "today",
+            limit: 10,
+          },
+        },
+      } as any);
+
+      expect(result.isError).toBeFalsy();
+      const responseData = JSON.parse(result.content[0].text);
+      
+      expect(responseData).toHaveProperty("announcements");
+      expect(responseData.filters_applied).toHaveProperty("date_range");
+      
+      // All announcements should be within the last month
+      if (responseData.announcements.length > 0) {
+        const oneMonthAgo = new Date();
+        oneMonthAgo.setMonth(oneMonthAgo.getMonth() - 1);
+        
+        responseData.announcements.forEach((ann: any) => {
+          const annDate = new Date(ann.date);
+          expect(annDate.getTime()).toBeGreaterThanOrEqual(oneMonthAgo.getTime());
+        });
+      }
+    }, 10000);
+  });
+
+  describe("get_recent_announcements", () => {
+    it("should fetch announcements from the past week", async () => {
+      const result = await server["handleToolCall"]({
+        params: {
+          name: "get_recent_announcements",
+          arguments: {
+            period: "1 week",
+          },
+        },
+      } as any);
+
+      expect(result.isError).toBeFalsy();
+      const responseData = JSON.parse(result.content[0].text);
+      
+      expect(responseData).toHaveProperty("announcements");
+      expect(responseData.filters_applied.date_range).toContain("week");
+      
+      // Check that announcements are from the past week if any exist
+      if (responseData.announcements.length > 0) {
+        const oneWeekAgo = new Date();
+        oneWeekAgo.setDate(oneWeekAgo.getDate() - 7);
+        
+        responseData.announcements.forEach((ann: any) => {
+          const annDate = new Date(ann.date);
+          expect(annDate.getTime()).toBeGreaterThanOrEqual(oneWeekAgo.getTime());
+        });
+      }
+    }, 10000);
+
+    it("should handle today filter", async () => {
+      const result = await server["handleToolCall"]({
+        params: {
+          name: "get_recent_announcements",
+          arguments: {
+            period: "0 days",
+          },
+        },
+      } as any);
+
+      expect(result.isError).toBeFalsy();
+      const responseData = JSON.parse(result.content[0].text);
+      
+      expect(responseData).toHaveProperty("announcements");
+      expect(responseData.filters_applied.date_range).toContain("0 days");
+      
+      // Today's announcements might be empty, that's okay
+      expect(Array.isArray(responseData.announcements)).toBe(true);
+    }, 10000);
+  });
+
+  describe("get_announcements_by_affinity_group", () => {
+    it("should handle affinity group filtering", async () => {
+      // We don't know specific affinity group IDs, so test with a made-up one
+      const result = await server["handleToolCall"]({
+        params: {
+          name: "get_announcements_by_affinity_group",
+          arguments: {
+            ag: "test-group-123",
+            limit: 5,
+          },
+        },
+      } as any);
+
+      expect(result.isError).toBeFalsy();
+      const responseData = JSON.parse(result.content[0].text);
+      
+      // Should return a valid response even if no announcements match
+      expect(responseData).toHaveProperty("announcements");
+      expect(Array.isArray(responseData.announcements)).toBe(true);
+      expect(responseData.filters_applied).toHaveProperty("affinity_group");
+      expect(responseData.filters_applied.affinity_group).toBe("test-group-123");
+    }, 10000);
+  });
+
+  describe("API Error Handling", () => {
+    it("should handle invalid parameters gracefully", async () => {
+      const result = await server["handleToolCall"]({
+        params: {
+          name: "get_announcements",
+          arguments: {
+            beginning_date: "invalid-date",
+          },
+        },
+      } as any);
+
+      // The API might accept this or reject it
+      // Just verify we get a response
+      expect(result).toBeDefined();
+      expect(result.content).toBeDefined();
+    }, 10000);
+
+    it("should handle empty results", async () => {
+      const result = await server["handleToolCall"]({
+        params: {
+          name: "get_announcements",
+          arguments: {
+            tags: "nonexistent-tag-xyz-123-456",
+            exact_match: true,
+          },
+        },
+      } as any);
+
+      expect(result.isError).toBeFalsy();
+      const responseData = JSON.parse(result.content[0].text);
+      
+      expect(responseData.total_announcements).toBe(0);
+      expect(responseData.announcements).toEqual([]);
+      expect(responseData.message).toContain("No announcements found");
+    }, 10000);
+  });
+});