@access-mcp/announcements 0.2.0 → 0.3.1

package/README.md

@@ -1,159 +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
 
-### **Recent Updates**
-
+### Searching Announcements
 ```
 "Recent ACCESS announcements"
-"Updates from past week"
-"Latest community news"
-"Announcements since January 2024"
+"Search for GPU announcements"
+"Find announcements about machine learning"
 ```
 
-### **System & Maintenance**
-
+### Creating Announcements
 ```
-"GPU maintenance announcements"
-"Delta maintenance notices"
-"Bridges-2 system updates"
-"Network-related announcements"
+"Help me create a new announcement"
+"I want to post an announcement about our workshop"
 ```
 
-### **By Topic**
-
+### Managing Your Announcements
 ```
-"Training workshops announced"
-"Machine learning updates"
-"Cloud computing announcements"
-"Allocation proposal news"
-"Python and PyTorch updates"
+"Show my announcements"
+"Update my draft announcement"
+"Delete my announcement"
 ```
 
 ## Tools
 
-### search_announcements
+### `search_announcements`
 
-Search and filter ACCESS support announcements with flexible 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: 'Anvil', 'ACCESS Support', 'DARWIN', 'Stampede-3'
-- `relative_start_date` - Filter from relative date. Examples: 'today', '-1 week', '-1 month', '-1 year'
-- `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: 25). Automatically rounded to valid API page sizes (5, 10, 25, or 50)
-
-**Usage Examples:**
+| 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) |
+
+**Returns:** `{ total, items: [{ uuid, title, summary, body, published_date, tags, affiliation, affinity_group }] }`
+
+**Examples:**
 ```javascript
-// Recent announcements
-search_announcements({
-  relative_start_date: "-1 month",
-  limit: 10
-})
-
-// Topic-specific search - GPU announcements
-search_announcements({
-  tags: "gpu,nvidia",
-  relative_start_date: "-1 year",
-  limit: 25
-})
-
-// System-specific search - Anvil announcements
-search_announcements({
-  ag: "Anvil",
-  relative_start_date: "-6 months",
-  limit: 15
-})
-
-// Machine learning announcements
-search_announcements({
-  tags: "machine-learning,ai",
-  relative_start_date: "-1 year",
-  limit: 20
-})
-
-// Combined filters - recent announcements for ACCESS Support
-search_announcements({
-  ag: "ACCESS Support",
-  tags: "maintenance",
-  relative_start_date: "-3 months",
-  limit: 10
-})
-
-// Exact date range search
-search_announcements({
-  tags: "training,professional-development",
-  start_date: "2024-01-01",
-  end_date: "2024-12-31",
-  limit: 25
-})
+// Full-text search
+search_announcements({ query: "GPU computing" })
+
+// GPU announcements from the past month
+search_announcements({ tags: "gpu", date: "this_month" })
+
+// Combined search
+search_announcements({ query: "workshop", tags: "training", limit: 10 })
 ```
 
-## Popular Tags
+### `get_announcement_context`
 
-Based on real ACCESS support announcements, here are commonly used tags:
+Get user context and available options before creating an announcement. **Call this first** when creating announcements.
 
-**Systems & Resources:**
-- `gpu`, `nvidia`, `anvil`, `delta`, `bridges-2`, `stampede2`, `stampede3`
-- `cloud-computing`, `openstack`, `kubernetes`, `containers`
+**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)
 
-**Technologies:**
-- `machine-learning`, `ai`, `deep-learning`, `python`, `pytorch`
-- `data-science`, `bioinformatics`, `molecular-dynamics`
-- `mpi`, `openmp`, `cuda`, `singularity`
+### `create_announcement`
 
-**Activities & Services:**
-- `training`, `professional-development`, `workshop`
-- `allocations-proposal`, `allocation-users`, `allocation-management`
-- `data-transfer`, `storage`, `file-system`
+Create a new ACCESS announcement (saved as draft for staff review).
 
-**Topics:**
-- `maintenance`, `performance-tuning`, `job-submission`
-- `security`, `networking`, `hpc-operations`
-- `documentation`, `community-outreach`
+**Parameters:**
+| 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) |
 
-## Common Affinity Groups
+**Returns:** `{ success, uuid, title, edit_url }`
 
-**ACCESS Systems:**
-- `ACCESS Support`, `DELTA`, `Anvil`, `Bridges-2`, `DARWIN`
-- `Stampede2`, `stampede3`, `osg`
+### `update_announcement`
 
-**Community Groups:**
-- `CSSN (Computational Science Support Network)`
-- `Open OnDemand`, `Pegasus`
-- `ACCESS Allocations`
+Update an existing announcement you own.
 
-## Response Format
+**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) |
 
-All tools return enhanced JSON responses with:
+**Returns:** `{ success, uuid, title, edit_url }`
 
-```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"
-  }
-}
-```
+### `delete_announcement`
+
+Permanently delete an announcement you own. **Requires explicit user confirmation.**
+
+**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 |
+
+**Important:** For bulk deletes, each announcement must be confirmed individually. General consent ("delete them all") is not sufficient.
+
+**Returns:** `{ success, uuid }`
+
+### `get_my_announcements`
+
+List all announcements created by the authenticated user.
+
+**Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `limit` | number | Max results (default: 50) |
+
+**Returns:** `{ total, items: [{ uuid, nid, title, status, created, published_date, summary, edit_url }] }`
 
 ## Installation
 
@@ -163,7 +132,7 @@ npm install -g @access-mcp/announcements
 
 ## Configuration
 
-### Claude Desktop
+For read-only access (searching public announcements):
 ```json
 {
   "mcpServers": {
@@ -175,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/server.d.ts

@@ -1,99 +1,94 @@
-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;
-                };
-                ag: {
-                    type: string;
-                    description: string;
-                };
-                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;
-                    format: string;
-                };
-                end_date: {
-                    type: string;
-                    description: string;
-                    format: string;
-                };
-                limit: {
-                    type: string;
-                    description: string;
-                    default: number;
-                };
-            };
-            examples: ({
-                name: string;
-                arguments: {
-                    relative_start_date: string;
-                    limit: number;
-                    tags?: undefined;
-                    ag?: undefined;
-                };
-            } | {
-                name: string;
-                arguments: {
-                    tags: string;
-                    relative_start_date: string;
-                    limit: number;
-                    ag?: undefined;
-                };
-            } | {
-                name: string;
-                arguments: {
-                    ag: string;
-                    relative_start_date: string;
-                    limit: number;
-                    tags?: undefined;
-                };
-            })[];
+    /**
+     * Get or create the Drupal auth provider for JSON:API write operations.
+     * Requires DRUPAL_API_URL, DRUPAL_USERNAME, and DRUPAL_PASSWORD env vars.
+     *
+     * Acting user is determined in priority order:
+     * 1. X-Acting-User header (from request context)
+     * 2. ACTING_USER environment variable (fallback)
+     */
+    private getDrupalAuth;
+    protected getTools(): Tool[];
+    protected getResources(): Resource[];
+    protected getPrompts(): Prompt[];
+    protected handleGetPrompt(request: {
+        params: {
+            name: string;
+            arguments?: Record<string, string>;
         };
-    }[];
-    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 searchAnnouncements;
-    private getPopularTags;
-    private getAffinityGroups;
+    /**
+     * Get the acting user's ACCESS ID for content attribution.
+     *
+     * Priority order:
+     * 1. X-Acting-User header (from request context)
+     * 2. ACTING_USER environment variable (fallback)
+     *
+     * Returns the ACCESS ID (e.g., "username@access-ci.org")
+     */
+    private getActingUserAccessId;
+    /**
+     * Create a new announcement via Drupal JSON:API
+     *
+     * The X-Acting-User header (set by DrupalAuthProvider) tells Drupal which
+     * ACCESS user is creating the content. Drupal handles user resolution.
+     */
+    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 ACCESS ID (e.g., "user@access-ci.org").
+     *
+     * The Drupal username should match the full ACCESS ID.
+     */
+    private getUserUuidByAccessId;
+    /**
+     * 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;
 }