@access-mcp/announcements 0.1.0 → 0.3.0

package/README.md

@@ -1,234 +1,128 @@
 # ACCESS Support Announcements MCP Server
 
-MCP server providing access to ACCESS support announcements, service updates, maintenance notices, and community communications. Stay informed about system changes, training opportunities, policy updates, and community events through the official ACCESS Support portal.
+MCP server for ACCESS support announcements, service updates, maintenance notices, and community communications. Supports both searching public announcements and creating/managing announcements for authenticated users.
 
 ## Usage Examples
 
-### **Stay Updated on Recent Activity**
-
-```
-"What's new with ACCESS?"
-"Show me recent announcements"
-"Any updates from ACCESS Support this week?"
-"What are the latest community announcements?"
-```
-
-### **Monitor System Maintenance & Issues**
-
+### Searching Announcements
 ```
-"Are there any GPU maintenance announcements?"
-"Show me maintenance notices for DELTA"
-"What system updates have been posted recently?"
-"Any announcements about Bridges-2 issues?"
-"Tell me about network-related announcements"
+"Recent ACCESS announcements"
+"Search for GPU announcements"
+"Find announcements about machine learning"
 ```
 
-### **Find Training & Educational Content**
-
+### Creating Announcements
 ```
-"Are there any training workshops announced?"
-"Show me machine learning training announcements"
-"What professional development opportunities are available?"
-"Any upcoming webinars or educational events?"
+"Help me create a new announcement"
+"I want to post an announcement about our workshop"
 ```
 
-### **Track Specific Systems or Communities**
-
+### Managing Your Announcements
 ```
-"Show me all announcements about Anvil"
-"What updates are there for the CSSN community?"
-"Any news from the Open OnDemand team?"
-"Show me Pegasus-related announcements"
-```
-
-### **Search by Topic or Technology**
-
-```
-"Find announcements about cloud computing"
-"Show me AI and machine learning updates"
-"Any announcements about allocation proposals?"
-"What's new with data science resources?"
-"Find announcements about Python or PyTorch"
-```
-
-### **Time-Based Searches**
-
-```
-"Show me announcements from the past month"
-"What was announced last week?"
-"Find announcements since January 1st, 2024"
-"Show me announcements from the past 6 months"
+"Show my announcements"
+"Update my draft announcement"
+"Delete my announcement"
 ```
 
 ## Tools
 
-### get_announcements
+### `search_announcements`
 
-Search ACCESS support announcements with comprehensive filtering options.
+Search and filter ACCESS support announcements (public, read-only).
 
 **Parameters:**
-- `tags` - Filter by topics (comma-separated). Examples: 'gpu,nvidia', 'machine-learning,ai', 'training,workshop'
-- `ag` - Filter by system/community group. Examples: 'DELTA', 'Anvil', 'ACCESS Support', 'CSSN (Computational Science Support Network)'
-- `relative_start_date` - Filter from relative date. Examples: 'today', '-1 week', '-1 month', '-3 months'
-- `relative_end_date` - Filter to relative date. Examples: 'now', 'today', '-1 week', '+1 week'
-- `start_date` - Filter from exact date (YYYY-MM-DD). Example: '2024-01-01'
-- `end_date` - Filter to exact date (YYYY-MM-DD). Example: '2024-12-31'
-- `limit` - Maximum results (default: 20)
-
-**Usage Examples:**
-```javascript
-// Recent GPU-related announcements
-get_announcements({
-  tags: "gpu,nvidia",
-  relative_start_date: "-1 month",
-  limit: 10
-})
-
-// DELTA system announcements from this year
-get_announcements({
-  ag: "DELTA",
-  start_date: "2024-01-01",
-  limit: 15
-})
-
-// Training announcements from the past 3 months
-get_announcements({
-  tags: "training,professional-development",
-  relative_start_date: "-3 months",
-  limit: 20
-})
-```
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string | Full-text search across title, body, and summary |
+| `tags` | string | Filter by topics (e.g., "gpu", "machine-learning", "training") |
+| `date` | enum | Time period: `today`, `this_week` (last 7 days), `this_month` (last 30 days), `past` (last year) |
+| `limit` | number | Max results (default: 25) |
 
-### get_announcements_by_tags
+**Returns:** `{ total, items: [{ uuid, title, summary, body, published_date, tags, affiliation, affinity_group }] }`
 
-Find announcements about specific topics or systems.
+**Examples:**
+```javascript
+// Full-text search
+search_announcements({ query: "GPU computing" })
 
-**Parameters:**
-- `tags` (required) - Specific topics (comma-separated). Examples: 'gpu,nvidia', 'data-science,python', 'cloud-computing'
-- `limit` - Maximum results (default: 10)
+// GPU announcements from the past month
+search_announcements({ tags: "gpu", date: "this_month" })
 
-**Usage Examples:**
-```javascript
-// Machine learning and AI announcements
-get_announcements_by_tags({
-  tags: "machine-learning,ai,deep-learning",
-  limit: 15
-})
-
-// Cloud computing updates
-get_announcements_by_tags({
-  tags: "cloud-computing,openstack",
-  limit: 10
-})
+// Combined search
+search_announcements({ query: "workshop", tags: "training", limit: 10 })
 ```
 
-### get_announcements_by_affinity_group
-
-Get announcements for specific ACCESS systems or community groups.
+### `get_announcement_context`
 
-**Parameters:**
-- `ag` (required) - System or community name. Examples: 'DELTA', 'Anvil', 'Bridges-2', 'ACCESS Support', 'Open OnDemand'
-- `limit` - Maximum results (default: 10)
+Get user context and available options before creating an announcement. **Call this first** when creating announcements.
 
-**Usage Examples:**
-```javascript
-// All DELTA-related announcements
-get_announcements_by_affinity_group({
-  ag: "DELTA",
-  limit: 20
-})
-
-// Open OnDemand community updates
-get_announcements_by_affinity_group({
-  ag: "Open OnDemand",
-  limit: 10
-})
-```
+**Returns:**
+- `tags`: Available tags for announcements
+- `affinity_groups`: Groups the user coordinates (empty if not a coordinator)
+- `is_coordinator`: Boolean - whether user can associate announcements with affinity groups
+- `affiliations`: Available affiliation options ("ACCESS Collaboration", "Community")
+- `where_to_share_options`: Available sharing options (for coordinators)
 
-### get_recent_announcements
+### `create_announcement`
 
-Get the latest announcements from a recent time period.
+Create a new ACCESS announcement (saved as draft for staff review).
 
 **Parameters:**
-- `period` - Time period to look back. Examples: '1 week', '2 weeks', '1 month', '3 months' (default: '1 month')
-- `limit` - Maximum results (default: 10)
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | string | Yes | Clear, specific headline (under 100 characters) |
+| `body` | string | Yes | Full content. HTML supported (`<p>`, `<a>`, `<strong>`, `<em>`, `<ul>`, `<li>`) |
+| `summary` | string | Yes | Brief teaser (1-2 sentences) for listings |
+| `tags` | array | No | Tag names to categorize the announcement |
+| `affiliation` | string | No | "ACCESS Collaboration" or "Community" (default) |
+| `affinity_group` | string | No | Group name/UUID (coordinators only) |
+| `external_link` | object | No | `{ uri: "https://...", title: "Link text" }` |
+| `where_to_share` | array | No | Where to publish: "Announcements page", "Bi-Weekly Digest" (all users), "Affinity Group page", "Email to Affinity Group" (coordinators only) |
 
-**Usage Examples:**
-```javascript
-// Past week's announcements
-get_recent_announcements({
-  period: "1 week",
-  limit: 15
-})
-
-// Past 3 months overview
-get_recent_announcements({
-  period: "3 months",
-  limit: 25
-})
-```
+**Returns:** `{ success, uuid, title, edit_url }`
 
-## Popular Tags
+### `update_announcement`
 
-Based on real ACCESS support announcements, here are commonly used tags:
+Update an existing announcement you own.
 
-**Systems & Resources:**
-- `gpu`, `nvidia`, `anvil`, `delta`, `bridges-2`, `stampede2`, `stampede3`
-- `cloud-computing`, `openstack`, `kubernetes`, `containers`
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `uuid` | string | Yes | Announcement UUID (from `get_my_announcements`) |
+| `title` | string | No | New title |
+| `body` | string | No | New body content |
+| `summary` | string | No | New summary |
+| `tags` | array | No | New tags |
+| `affinity_group` | string | No | New affinity group |
+| `external_link` | object | No | New external link |
+| `where_to_share` | array | No | Where to publish (see create_announcement for options) |
 
-**Technologies:**
-- `machine-learning`, `ai`, `deep-learning`, `python`, `pytorch`
-- `data-science`, `bioinformatics`, `molecular-dynamics`
-- `mpi`, `openmp`, `cuda`, `singularity`
+**Returns:** `{ success, uuid, title, edit_url }`
 
-**Activities & Services:**
-- `training`, `professional-development`, `workshop`
-- `allocations-proposal`, `allocation-users`, `allocation-management`
-- `data-transfer`, `storage`, `file-system`
+### `delete_announcement`
 
-**Topics:**
-- `maintenance`, `performance-tuning`, `job-submission`
-- `security`, `networking`, `hpc-operations`
-- `documentation`, `community-outreach`
+Permanently delete an announcement you own. **Requires explicit user confirmation.**
 
-## Common Affinity Groups
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `uuid` | string | Yes | Announcement UUID |
+| `confirmed` | boolean | Yes | Must be `true` - only set after showing the user the title/status and getting explicit confirmation |
 
-**ACCESS Systems:**
-- `ACCESS Support`, `DELTA`, `Anvil`, `Bridges-2`, `DARWIN`
-- `Stampede2`, `stampede3`, `osg`
+**Important:** For bulk deletes, each announcement must be confirmed individually. General consent ("delete them all") is not sufficient.
 
-**Community Groups:**
-- `CSSN (Computational Science Support Network)`
-- `Open OnDemand`, `Pegasus`
-- `ACCESS Allocations`
+**Returns:** `{ success, uuid }`
 
-## Response Format
+### `get_my_announcements`
 
-All tools return enhanced JSON responses with:
+List all announcements created by the authenticated user.
 
-```json
-{
-  "total_announcements": 42,
-  "filtered_announcements": 10,
-  "announcements": [
-    {
-      "title": "Scheduled Maintenance: DELTA GPU Nodes",
-      "body": "DELTA GPU nodes will undergo maintenance...",
-      "date": "2024-03-15",
-      "formatted_date": "March 15, 2024",
-      "author": "ACCESS Support",
-      "tags": ["maintenance", "gpu", "delta"],
-      "affinity_groups": ["DELTA"],
-      "body_preview": "DELTA GPU nodes will undergo maintenance from 9 AM to 5 PM..."
-    }
-  ],
-  "popular_tags": ["gpu", "maintenance", "delta"],
-  "filters_applied": {
-    "tags": "gpu,maintenance",
-    "date_range": "-1 month to now"
-  }
-}
-```
+**Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `limit` | number | Max results (default: 50) |
+
+**Returns:** `{ total, items: [{ uuid, nid, title, status, created, published_date, summary, edit_url }] }`
 
 ## Installation
 
@@ -238,7 +132,7 @@ npm install -g @access-mcp/announcements
 
 ## Configuration
 
-### Claude Desktop
+For read-only access (searching public announcements):
 ```json
 {
   "mcpServers": {
@@ -250,27 +144,29 @@ npm install -g @access-mcp/announcements
 }
 ```
 
-### Local Development
+For full access (creating/managing announcements), authentication is required:
 ```json
 {
   "mcpServers": {
     "access-announcements": {
-      "command": "/opt/homebrew/bin/node",
-      "args": ["/path/to/access_mcp/packages/announcements/dist/index.js"]
+      "command": "npx",
+      "args": ["@access-mcp/announcements"],
+      "env": {
+        "DRUPAL_API_URL": "https://support.access-ci.org",
+        "DRUPAL_USERNAME": "your-username",
+        "DRUPAL_PASSWORD": "your-password",
+        "ACTING_USER_UID": "12345"
+      }
     }
   }
 }
 ```
 
-## Testing
+## Resources
 
-```bash
-# Unit tests
-npm test
+- `accessci://announcements` - Recent announcements (10 most recent)
 
-# Integration tests (requires API access)
-npm run test:integration
+## Prompts
 
-# All tests
-npm run test:all
-```
+- `create_announcement_guide` - Step-by-step guide for creating announcements
+- `manage_announcements_guide` - Guide for viewing, updating, and deleting announcements

package/dist/index.js

@@ -1,24 +1,9 @@
 #!/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();
-    }
+    const port = process.env.PORT ? parseInt(process.env.PORT, 10) : undefined;
+    await server.start(port ? { httpPort: port } : undefined);
 }
 main().catch((error) => {
     // Log errors to stderr and exit

package/dist/server.d.ts

@@ -1,156 +1,80 @@
-import { BaseAccessServer } from "@access-mcp/shared";
+import { BaseAccessServer, Tool, Resource, CallToolResult } from "@access-mcp/shared";
+import { CallToolRequest, ReadResourceRequest, ReadResourceResult, GetPromptResult, Prompt } from "@modelcontextprotocol/sdk/types.js";
 export declare class AnnouncementsServer extends BaseAccessServer {
+    private drupalAuth?;
+    private tagCache;
+    private tagCacheExpiry?;
+    private static TAG_CACHE_TTL_MS;
     constructor();
-    protected getTools(): ({
-        name: string;
-        description: string;
-        inputSchema: {
-            type: string;
-            properties: {
-                tags: {
-                    type: string;
-                    description: string;
-                    required?: undefined;
-                };
-                ag: {
-                    type: string;
-                    description: string;
-                    required?: undefined;
-                };
-                affiliation: {
-                    type: string;
-                    description: string;
-                };
-                relative_start_date: {
-                    type: string;
-                    description: string;
-                };
-                relative_end_date: {
-                    type: string;
-                    description: string;
-                };
-                start_date: {
-                    type: string;
-                    description: string;
-                };
-                end_date: {
-                    type: string;
-                    description: string;
-                };
-                limit: {
-                    type: string;
-                    description: string;
-                    default: number;
-                };
-                period?: undefined;
-            };
-            required?: undefined;
+    /**
+     * Get or create the Drupal auth provider for JSON:API write operations.
+     * Requires DRUPAL_API_URL, DRUPAL_USERNAME, and DRUPAL_PASSWORD env vars.
+     */
+    private getDrupalAuth;
+    protected getTools(): Tool[];
+    protected getResources(): Resource[];
+    protected getPrompts(): Prompt[];
+    protected handleGetPrompt(request: {
+        params: {
+            name: string;
+            arguments?: Record<string, string>;
         };
-    } | {
-        name: string;
-        description: string;
-        inputSchema: {
-            type: string;
-            properties: {
-                tags: {
-                    type: string;
-                    description: string;
-                    required: boolean;
-                };
-                limit: {
-                    type: string;
-                    description: string;
-                    default: number;
-                };
-                ag?: undefined;
-                affiliation?: undefined;
-                relative_start_date?: undefined;
-                relative_end_date?: undefined;
-                start_date?: undefined;
-                end_date?: undefined;
-                period?: undefined;
-            };
-            required: string[];
-        };
-    } | {
-        name: string;
-        description: string;
-        inputSchema: {
-            type: string;
-            properties: {
-                ag: {
-                    type: string;
-                    description: string;
-                    required: boolean;
-                };
-                limit: {
-                    type: string;
-                    description: string;
-                    default: number;
-                };
-                tags?: undefined;
-                affiliation?: undefined;
-                relative_start_date?: undefined;
-                relative_end_date?: undefined;
-                start_date?: undefined;
-                end_date?: undefined;
-                period?: undefined;
-            };
-            required: string[];
-        };
-    } | {
-        name: string;
-        description: string;
-        inputSchema: {
-            type: string;
-            properties: {
-                period: {
-                    type: string;
-                    description: string;
-                    default: string;
-                };
-                limit: {
-                    type: string;
-                    description: string;
-                    default: number;
-                };
-                tags?: undefined;
-                ag?: undefined;
-                affiliation?: undefined;
-                relative_start_date?: undefined;
-                relative_end_date?: undefined;
-                start_date?: undefined;
-                end_date?: undefined;
-            };
-            required?: undefined;
-        };
-    })[];
-    protected getResources(): {
-        uri: string;
-        name: string;
-        description: string;
-        mimeType: string;
-    }[];
-    handleToolCall(request: any): Promise<{
-        content: {
-            type: string;
-            text: string;
-        }[];
-    }>;
-    handleResourceRead(request: any): Promise<{
-        contents: {
-            uri: any;
-            mimeType: string;
-            text: string;
-        }[];
-    }>;
+    }): Promise<GetPromptResult>;
+    protected handleToolCall(request: CallToolRequest): Promise<CallToolResult>;
+    protected handleResourceRead(request: ReadResourceRequest): Promise<ReadResourceResult>;
+    private normalizeLimit;
     private buildAnnouncementsUrl;
     private fetchAnnouncements;
     private enhanceAnnouncements;
-    private getAnnouncements;
-    private getAnnouncementsByTags;
-    private getAnnouncementsByAffinityGroup;
-    private getRecentAnnouncements;
-    private getPopularTags;
-    private getAffinityGroups;
+    private searchAnnouncements;
+    /**
+     * Get the acting user's UID from environment variable.
+     * This identifies who the announcement should be attributed to.
+     */
+    private getActingUserUid;
+    /**
+     * Create a new announcement via Drupal JSON:API
+     */
+    private createAnnouncement;
+    /**
+     * Update an existing announcement via Drupal JSON:API
+     */
+    private updateAnnouncement;
+    /**
+     * Delete an announcement via Drupal JSON:API
+     */
+    private deleteAnnouncement;
+    /**
+     * Get announcements created by the acting user
+     */
+    private getMyAnnouncements;
+    /**
+     * Get a user's UUID by their Drupal user ID (internal helper)
+     */
+    private getUserUuidByUid;
+    /**
+     * Get announcement context - tags, affinity groups, and options for creating announcements
+     */
+    private getAnnouncementContext;
+    /**
+     * Look up affinity group UUID by ID or name
+     */
+    private getAffinityGroupUuid;
+    /**
+     * Map human-friendly "where to share" labels to Drupal values
+     */
+    private static WHERE_TO_SHARE_MAP;
+    private normalizeWhereToShare;
+    /**
+     * Check if tag cache is still valid
+     */
+    private isTagCacheValid;
+    /**
+     * Populate the tag cache with all available tags
+     */
+    private populateTagCache;
+    /**
+     * Get tag UUIDs by their names (with caching)
+     */
+    private getTagUuidsByName;
 }