PROJECT_SUMMARY.md•5 kB
# Network School Events MCP Server - Project Summary
## ✅ Complete and Ready to Use
This MCP server is fully functional and ready to connect to Claude Desktop.
## What Was Built
### Core Functionality ✓
**Four MCP Tools:**
1. `get_todays_events` - Fetches events happening today
2. `get_upcoming_events` - Fetches events in the next N days (default: 7)
3. `search_events` - Searches events by keyword
4. `register_for_event` - Register for events with name and email
**MCP Resources (Wiki):**
- Access Network School wiki pages on-demand
- Automatic discovery of all markdown files in `wiki/` folder
- Token-efficient: only loads content when Claude needs it
- Easy to add new pages - just drop `.md` files in the folder!
### Tech Stack ✓
- TypeScript with strict type checking
- Node.js (any version)
- axios for reliable HTTP requests
- @modelcontextprotocol/sdk v1.0.4
- date-fns v4.1.0 + date-fns-tz v3.2.0
- Compiled to ES2022 modules
### Project Structure ✓
```
ns-mcp/
├── src/
│ ├── index.ts # MCP server entry point with stdio transport
│ ├── luma-client.ts # Luma API client with error handling
│ ├── formatters.ts # Event formatting and filtering logic
│ ├── types.ts # TypeScript interfaces for Luma API
│ └── test.ts # API connection test script
├── build/ # Compiled JavaScript output (ready to run)
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── README.md # Main documentation
├── SETUP.md # Step-by-step setup guide
├── claude_config_example.json # Ready-to-use Claude Desktop config
└── .gitignore # Git ignore rules
```
### Features ✓
**Event Formatting:**
- Beautiful bullet-list format with all event details
- Event API ID for easy registration
- Date labels: "Today", "Tomorrow", or full date
- Time ranges with timezone abbreviations
- Location with online/offline indicator
- Host names from the hosts array
- Ticket info (free/paid, price, registration count)
- Direct links to lu.ma event pages
**Event Registration:**
- Automatic ticket type detection
- Validates event exists before registration
- Returns ticket key and confirmation details
- Supports phone number and timezone options
- Graceful error handling with detailed messages
**Date Handling:**
- Parses ISO 8601 timestamps from API
- Filters by date ranges accurately
- Respects event timezones for display
- Uses date-fns for reliable date operations
**Error Handling:**
- Graceful API failure handling
- User-friendly error messages
- Input validation for tool parameters
- Empty results handled with helpful messages
**Quality:**
- Zero linter errors
- Strict TypeScript types throughout
- Production-ready code quality
- Comprehensive documentation
## Quick Start
1. **Install & Build:**
```bash
cd /Users/akashkumar/Code/ns-mcp
npm install
npm run build
```
2. **Test:**
```bash
npm test
```
3. **Configure Claude Desktop:**
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"network-school-events": {
"command": "node",
"args": ["/Users/akashkumar/Code/ns-mcp/build/index.js"]
}
}
}
```
4. **Restart Claude Desktop**
5. **Try it:**
- "What Network School events are happening today?"
- "Show me events in the next 2 weeks"
- "Search for hackathon events"
- "Register me for the Vibecoding event with name John Doe and email john@example.com"
## API Details
- **Endpoint:** https://api2.luma.com/calendar/get-items
- **Calendar:** cal-4dWxlBFjW9Cd6ou (Network School public calendar)
- **Authentication:** None required (public calendar)
- **Caching:** None (always fetches fresh data)
## Testing Results
The test script successfully:
- ✓ Connected to Luma API
- ✓ Fetched 7 events
- ✓ Formatted events correctly with all details
- ✓ Applied date filters properly
- ✓ Displayed timezones correctly (GMT+8)
- ✓ Showed "Today" and "Tomorrow" labels
- ✓ Listed hosts, tickets, and registration counts
## Files You Can Customize
- `src/formatters.ts` - Change event formatting output
- `src/luma-client.ts` - Modify API endpoint or add caching
- `src/index.ts` - Add more MCP tools or change tool schemas
After changes, rebuild:
```bash
npm run build
```
## Next Steps
1. Connect to Claude Desktop using SETUP.md
2. Test the tools by asking Claude about Network School events
3. (Optional) Customize the formatting or add new features
4. (Optional) Add this to your git repository
## Support
- See SETUP.md for detailed setup instructions
- See README.md for usage examples
- Check Claude Desktop logs if connection issues occur
- Run `npm test` to verify API connectivity
---
**Status:** ✅ Production Ready
**Version:** 1.0.0
**Built:** October 5, 2025