@access-mcp/events 0.1.0 → 0.3.0

package/README.md

@@ -6,10 +6,7 @@ A Model Context Protocol server providing access to ACCESS-CI events data includ
 
 ### 🔧 Tools
 
-- **`get_events`** - Get ACCESS-CI events with comprehensive filtering
-- **`get_upcoming_events`** - Get upcoming events (today onward)
-- **`search_events`** - Search events by keywords in title/description
-- **`get_events_by_tag`** - Get events filtered by specific tags
+- **`search_events`** - Comprehensive event search and filtering with native full-text search, date filters, topic/tag filtering, and more
 
 ### 📊 Resources
 
@@ -41,31 +38,49 @@ Add to your Claude Desktop configuration:
 }
 ```
 
-### Example Queries
+## Usage Examples
 
-**Get upcoming events:**
+### **Search & Discovery**
 
 ```
-What events are coming up in the next week?
+"Upcoming events next week"
+"Python workshops"
+"Machine learning events"
+"Office hours this week"
 ```
 
-**Search for specific topics:**
+### **Filtering**
 
 ```
-Find upcoming Python workshops
+"Beginner-level events this month"
+"GPU computing events"
+"Webinars in December"
+"Advanced training sessions"
 ```
 
-**Filter by skill level:**
+## Key Improvements
 
-```
-Show me beginner-level events this month
-```
+### 🚀 Enhanced Search (v2.1)
 
-**Get events by tags:**
+**Native API Full-Text Search:**
+- Searches across titles, descriptions, speakers, tags, location, and event type
+- Supports multi-word queries (e.g., "machine learning", "office hours")
+- Much more comprehensive results than previous tag-only filtering
+- Server-side indexing for better performance
 
-```
-Find all machine learning events
-```
+**Search Examples:**
+- `"python"` - Find Python programming events
+- `"machine learning"` - Find ML-related content in any field
+- `"gpu computing"` - Find GPU-related events
+- `"office hours"` - Find all office hours sessions
+
+### 🌍 Timezone Support (v2.1)
+
+**Smart Timezone Handling:**
+- All timestamps returned in UTC (ISO 8601 format with Z suffix)
+- Timezone parameter controls relative date calculations
+- Common timezone examples: `America/New_York`, `Europe/London`, `Asia/Tokyo`
+- Default: UTC calculations
 
 ## Filtering Capabilities
 
@@ -126,50 +141,94 @@ The server adds these computed fields:
 - `duration_hours` - Calculated event duration
 - `starts_in_hours` - Hours until event starts
 
-## Examples
-
-### Get Events with Multiple Filters
-
-```typescript
-// Get Python workshops for beginners in the next month
-{
-  "tool": "get_events",
-  "arguments": {
-    "beginning_date_relative": "today",
-    "end_date_relative": "+1month",
-    "event_type": "workshop",
-    "skill_level": "beginner",
-    "event_tags": "python"
-  }
-}
+## Tool Reference
+
+### search_events
+
+Comprehensive event search and filtering with native full-text search, date filters, and topic/tag filtering.
+
+**Parameters:**
+- `query` (string, optional): Search titles, descriptions, speakers, and tags
+- `type` (string, optional): Filter by event type (workshop, webinar, training)
+- `tags` (string, optional): Filter by tags (python, gpu, hpc, ml)
+- `date` (string, optional): Filter by time period. Valid values: `today`, `upcoming`, `past`, `this_week`, `this_month`
+- `skill` (string, optional): Filter by skill level. Valid values: `beginner`, `intermediate`, `advanced`
+- `limit` (number, optional): Maximum results (default: 50, automatically rounded to API page sizes: 25, 50, 75, or 100)
+
+## Usage Examples
+
+### Full-Text Search
+
+```javascript
+// Upcoming Python events
+search_events({
+  query: "python",
+  date: "upcoming",
+  limit: 10
+})
+
+// Machine learning workshops this month
+search_events({
+  query: "machine learning",
+  date: "this_month",
+  type: "workshop",
+  limit: 25
+})
+
+// Past office hours
+search_events({
+  query: "office hours",
+  date: "past",
+  limit: 30
+})
 ```
 
-### Search Events
-
-```typescript
-// Search for GPU-related events
-{
-  "tool": "search_events",
-  "arguments": {
-    "query": "GPU computing",
-    "beginning_date_relative": "today",
-    "limit": 10
-  }
-}
+### Filter by Tags and Type
+
+```javascript
+// All upcoming GPU events
+search_events({
+  tags: "gpu",
+  date: "upcoming",
+  limit: 20
+})
+
+// Beginner training sessions
+search_events({
+  type: "training",
+  skill: "beginner",
+  date: "upcoming",
+  limit: 15
+})
+
+// Python workshops for beginners
+search_events({
+  date: "this_month",
+  type: "workshop",
+  skill: "beginner",
+  tags: "python",
+  limit: 25
+})
 ```
 
-### Get Events by Tag
-
-```typescript
-// Get all machine learning events this month
-{
-  "tool": "get_events_by_tag",
-  "arguments": {
-    "tag": "machine-learning",
-    "time_range": "this_month",
-    "limit": 20
-  }
-}
+### Timezone-Aware Searches
+
+```javascript
+// Get events in New York timezone
+search_events({
+  beginning_date_relative: "today",
+  end_date_relative: "+1week",
+  timezone: "America/New_York",
+  limit: 30
+})
+
+// Get events in Europe/London timezone
+search_events({
+  query: "workshop",
+  beginning_date_relative: "today",
+  timezone: "Europe/London",
+  limit: 25
+})
 ```
 
 ## Development
@@ -187,10 +246,18 @@ npm test
 
 ## Base URL
 
-The server connects to: `https://support.access-ci.org/api/2.0/events`
+The server connects to: `https://support.access-ci.org/api/2.2/events`
 
 ## Technical Notes
 
+### API Version 2.2 Features
+- **UTC timestamps**: All dates returned in UTC with Z suffix (e.g., `2024-08-30T13:00:00Z`)
+- **Native search**: Uses `search_api_fulltext` parameter for comprehensive searching
+- **Timezone support**: Relative dates calculated using specified timezone
+- **Pagination**: API accepts specific page sizes (25, 50, 75, or 100). Requested limits are automatically rounded to nearest valid size.
+- **Enhanced metadata**: Responses include API version and timezone info
+
+### General
 - All date comparisons use the event's start date (`date` field)
 - Results include both upcoming and past events unless date filtered
 - Faceted search filters use AND logic when combined

package/dist/index.js

@@ -2,7 +2,8 @@
 import { EventsServer } from "./server.js";
 async function main() {
     const server = new EventsServer();
-    await server.start();
+    const port = process.env.PORT ? parseInt(process.env.PORT, 10) : undefined;
+    await server.start(port ? { httpPort: port } : undefined);
 }
 if (import.meta.url === `file://${process.argv[1]}`) {
     main().catch((error) => {

package/dist/server.d.ts

@@ -4,90 +4,7 @@ export declare class EventsServer extends BaseAccessServer {
     private _eventsHttpClient?;
     constructor();
     protected get httpClient(): AxiosInstance;
-    protected getTools(): ({
-        name: string;
-        description: string;
-        inputSchema: {
-            type: string;
-            properties: {
-                beginning_date_relative: {
-                    type: string;
-                    description: string;
-                    enum: string[];
-                    default?: undefined;
-                };
-                end_date_relative: {
-                    type: string;
-                    description: string;
-                    enum: string[];
-                };
-                beginning_date: {
-                    type: string;
-                    description: string;
-                };
-                end_date: {
-                    type: string;
-                    description: string;
-                };
-                event_type: {
-                    type: string;
-                    description: string;
-                };
-                event_affiliation: {
-                    type: string;
-                    description: string;
-                };
-                skill_level: {
-                    type: string;
-                    description: string;
-                    enum: string[];
-                };
-                event_tags: {
-                    type: string;
-                    description: string;
-                };
-                limit: {
-                    type: string;
-                    description: string;
-                    minimum: number;
-                    maximum: number;
-                };
-                query?: undefined;
-                tag?: undefined;
-                time_range?: undefined;
-            };
-            required: never[];
-        };
-    } | {
-        name: string;
-        description: string;
-        inputSchema: {
-            type: string;
-            properties: {
-                limit: {
-                    type: string;
-                    description: string;
-                    minimum: number;
-                    maximum: number;
-                };
-                event_type: {
-                    type: string;
-                    description: string;
-                };
-                beginning_date_relative?: undefined;
-                end_date_relative?: undefined;
-                beginning_date?: undefined;
-                end_date?: undefined;
-                event_affiliation?: undefined;
-                skill_level?: undefined;
-                event_tags?: undefined;
-                query?: undefined;
-                tag?: undefined;
-                time_range?: undefined;
-            };
-            required: never[];
-        };
-    } | {
+    protected getTools(): {
         name: string;
         description: string;
         inputSchema: {
@@ -97,65 +14,32 @@ export declare class EventsServer extends BaseAccessServer {
                     type: string;
                     description: string;
                 };
-                beginning_date_relative: {
+                type: {
                     type: string;
                     description: string;
-                    default: string;
-                    enum?: undefined;
                 };
-                limit: {
+                tags: {
                     type: string;
                     description: string;
-                    minimum: number;
-                    maximum: number;
                 };
-                end_date_relative?: undefined;
-                beginning_date?: undefined;
-                end_date?: undefined;
-                event_type?: undefined;
-                event_affiliation?: undefined;
-                skill_level?: undefined;
-                event_tags?: undefined;
-                tag?: undefined;
-                time_range?: undefined;
-            };
-            required: string[];
-        };
-    } | {
-        name: string;
-        description: string;
-        inputSchema: {
-            type: string;
-            properties: {
-                tag: {
+                date: {
                     type: string;
                     description: string;
+                    enum: string[];
                 };
-                time_range: {
+                skill: {
                     type: string;
                     description: string;
                     enum: string[];
-                    default: string;
                 };
                 limit: {
                     type: string;
                     description: string;
-                    minimum: number;
-                    maximum: number;
+                    default: number;
                 };
-                beginning_date_relative?: undefined;
-                end_date_relative?: undefined;
-                beginning_date?: undefined;
-                end_date?: undefined;
-                event_type?: undefined;
-                event_affiliation?: undefined;
-                skill_level?: undefined;
-                event_tags?: undefined;
-                query?: undefined;
             };
-            required: string[];
         };
-    })[];
+    }[];
     protected getResources(): {
         uri: string;
         name: string;
@@ -170,15 +54,12 @@ export declare class EventsServer extends BaseAccessServer {
     }>;
     handleResourceRead(request: any): Promise<{
         contents: {
-            uri: any;
+            uri: string;
             mimeType: string;
             text: string;
         }[];
     }>;
     private buildEventsUrl;
     private getEvents;
-    private getUpcomingEvents;
     private searchEvents;
-    private getEventsByTag;
-    private getPopularTags;
 }