whocaresthat/mcp-notification-server

MCP Notification Server - Complete Demonstration

A comprehensive, production-ready demonstration of MCP (Model Context Protocol) notifications and subscriptions with working examples, multiple patterns, interactive demos, and complete documentation.

🎯 What's This?

This repository provides the most complete demonstration of MCP notifications available, including:

• Working server implementations (basic and advanced)
• Interactive client demos
• Real-world notification patterns
• Comprehensive testing scenarios
• Complete architecture documentation
• Step-by-step guides

Perfect for learning how to implement notifications in your own MCP servers!

⚡ Quick Start

Get running in 5 minutes →

git clone https://github.com/whocaresthat/mcp-notification-server.git
cd mcp-notification-server
npm install
npm run build

# Run interactive demo
node dist/examples/client.js

📚 Complete Documentation

✨ Features

Three Implementation Levels

1. Basic Server ()

   • Simple, easy to understand
   • Core notification concepts
   • Perfect for learning

2. Advanced Server ()

   • File system watching
   • Webhook endpoints
   • Periodic updates
   • Production patterns

3. Interactive Client ()

   • Full client implementation
   • Automated demo
   • Shows notifications in action

Comprehensive Examples

✅ Event-driven notifications ✅ Periodic updates (timers) ✅ File system monitoring ✅ Webhook integration ✅ Threshold-based alerts ✅ Batched notifications ✅ Multiple subscribers ✅ Subscription lifecycle management

🎓 What You'll Learn

For Beginners

• ✓ What are MCP notifications?
• ✓ How to enable subscriptions
• ✓ Sending your first notification
• ✓ Testing with Claude Desktop

For Advanced Users

• ✓ Production-ready patterns
• ✓ Performance optimization
• ✓ Error handling strategies
• ✓ Security considerations
• ✓ Scalability patterns

🚀 Usage

Option 1: Interactive Demo

npm install
npm run build
node dist/examples/client.js

See notifications in action with automated demo!

Option 2: Claude Desktop

Add to your Claude config:

{
  "mcpServers": {
    "notification-demo": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-notification-server/dist/index.js"]
    }
  }
}

Then try in Claude:

• "Subscribe to counter://main"
• "Increment the counter by 5"
• "What's the current counter value?"

Option 3: MCP Inspector

npx @modelcontextprotocol/inspector dist/index.js

Open http://localhost:5173 for interactive testing.

Option 4: Custom Integration

Use the code as a template for your own MCP server!

📖 Documentation Highlights

Architecture Overview

Client ──subscribe──> Server
Client <──notify──────┘

The server:

1. Accepts subscriptions from clients
2. Monitors resources for changes
3. Automatically notifies subscribers
4. Manages subscription lifecycle

See for complete details.

Notification Patterns

From :

1. Event-Driven - User actions trigger notifications
2. Periodic - Regular updates (timers)
3. File System - Monitor file changes
4. Threshold - Alert on important values
5. Batched - Group notifications
6. Filtered - Conditional updates
7. Cascading - Related resource updates

Test Scenarios

From :

• Basic subscribe and notify
• Multiple subscribers
• Unsubscribe behavior
• Multiple resources
• Error handling
• Performance under load
• Connection loss recovery
• And more...

🎯 Real-World Use Cases

This demonstration shows patterns for:

• 📊 Real-time Dashboards - Live data updates
• 🔍 System Monitoring - Health checks and alerts
• 📁 File Synchronization - Hot-reload configurations
• 📝 Log Streaming - Real-time log viewing
• 🚨 Alert Systems - Threshold-based notifications
• 👥 Collaboration Tools - Multi-user updates
• 📈 Analytics - Live metrics tracking

📦 What's Included

mcp-notification-server/
├── 📄 QUICKSTART.md              # 5-minute setup guide
├── 📄 DEMO.md                    # Interactive walkthrough
├── 📄 ARCHITECTURE.md            # System design docs
├── src/
│   └── index.ts                  # Basic server (start here!)
├── examples/
│   ├── advanced-server.ts        # Production patterns
│   ├── client.ts                 # Interactive demo
│   ├── patterns.md               # 7 notification patterns
│   ├── test-scenarios.md         # Testing guide
│   └── run-demo.sh               # Easy demo runner
├── package.json
└── tsconfig.json

🔧 Development

# Install dependencies
npm install

# Build everything
npm run build

# Run basic server
npm start

# Run advanced server
node dist/examples/advanced-server.js

# Run interactive client demo
node dist/examples/client.js

📊 Code Examples

Minimal Server

import { Server } from "@modelcontextprotocol/sdk/server/index.js";

const server = new Server(
  { name: "my-server", version: "1.0.0" },
  { capabilities: { resources: { subscribe: true } } }
);

// Handle subscriptions
server.setRequestHandler(SubscribeRequestSchema, async (request) => {
  subscriptions.set(clientId, request.params.uri);
  return {};
});

// Send notifications
await server.notification({
  method: "notifications/resources/updated",
  params: { uri: "resource://example" }
});

Minimal Client

import { Client } from "@modelcontextprotocol/sdk/client/index.js";

// Handle notifications
client.setNotificationHandler({
  method: "notifications/resources/updated",
  handler: async (notification) => {
    console.log(`Updated: ${notification.params.uri}`);
  }
});

// Subscribe
await client.request({
  method: "resources/subscribe",
  params: { uri: "resource://example" }
});

🧪 Testing

Run the comprehensive test scenarios:

# See all test scenarios
cat examples/test-scenarios.md

# Run with MCP Inspector
npx @modelcontextprotocol/inspector dist/index.js

🌟 Key Features

🤝 Contributing

Contributions welcome! Please:

1. Read
2. Check
3. Add tests for new features
4. Update documentation

📚 Learn More

• 📖 MCP Specification
• 🔧 MCP TypeScript SDK
• 🌐 MCP Documentation
• 💬 MCP Community

🎯 Next Steps

1. Start Here →
2. Try Demo → node dist/examples/client.js
3. Read Patterns →
4. Understand Design →
5. Build Your Own → Use this as a template!

📄 License

MIT License - See file for details

🌟 Why This Repository?

This is the most comprehensive MCP notification demonstration available because it includes:

• ✅ Three levels of implementation (basic, advanced, client)
• ✅ Seven real-world notification patterns
• ✅ Complete architecture documentation
• ✅ Ten comprehensive test scenarios
• ✅ Interactive demos you can run immediately
• ✅ Production-ready code you can use as a template
• ✅ Step-by-step guides for every skill level

Ready to master MCP notifications? Start with ! 🚀