Merge pull request #2 from featureform/example/smack-server

Example/smack server

Author: RiddhiBagadiaa

examples/servers/docker-compose.yml

@@ -0,0 +1,25 @@
+services:
+  smack-server:
+    build: ./smack
+    ports:
+      - "8000:8000"
+    restart: unless-stopped
+    depends_on:
+      - postgres
+    environment:
+      - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/smack
+      
+  postgres:
+    image: postgres:15
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    environment:
+      - POSTGRES_PASSWORD=postgres
+      - POSTGRES_USER=postgres
+      - POSTGRES_DB=smack
+    restart: unless-stopped
+
+volumes:
+  postgres_data:

examples/servers/smack/Dockerfile

@@ -0,0 +1,29 @@
+FROM python:3.10-slim
+
+# Set working directory in the container
+WORKDIR /app
+
+# Install uv and tomli for TOML parsing
+RUN pip install --no-cache-dir uv tomli==2.0.1
+
+# Copy pyproject.toml
+COPY pyproject.toml .
+
+# Install dependencies using uv with --system flag
+RUN uv pip install --system --no-cache-dir .
+
+# Copy the application code
+COPY . .
+
+# Expose port for the server
+EXPOSE 8000
+
+# Environment variables for PostgreSQL connection
+ENV DB_HOST=postgres \
+    DB_NAME=smack \
+    DB_USER=postgres \
+    DB_PASSWORD=postgres \
+    DB_PORT=5432
+
+# Command to run the web server
+CMD ["python", "mcp_smack/server.py"]

examples/servers/smack/README.md

@@ -0,0 +1,111 @@
+# SMACK - Message Storage Service
+
+SMACK is a simple messaging service with a persistent message store using PostgreSQL. It's designed to work with the Model Context Protocol (MCP) Inspector for easy testing and interaction.
+
+## Overview
+
+SMACK is built on the MCP Engine, a secure implementation of the Model Context Protocol (MCP) with authentication support. While MCP standardizes interactions between AI models and external systems, early implementations lacked key features for security, scalability, and reliability. MCP Engine addresses these by integrating OAuth 2.1, ensuring secure and seamless communication.
+
+SMACK serves as a practical demonstration of the MCP Engine's capabilities by providing a basic yet functional messaging service. It highlights the importance of authentication and provides a hands-on experience with secure AI interactions.
+
+For a visual representation of the architecture and how SMACK integrates with the MCP Engine, please refer to the diagram below:
+
+<a href="https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/authorization/" target="_blank">
+  <img src="https://cdn.prod.website-files.com/60cce6512b4ab924a0427124/67ec3d30ae1829e736099100_AD_4nXfpxfRMRgTM8glCYWi-YjhvxBvM3qAS73e58YRbCT8xtVnDwipEhT6NhLxssr5xH7jw-d6HoJByggT7QtOIsXYuG8MYbVtiV2aeNPiXDlIGjIF6zIKhaCrO4AdmGAUmuHLXgBzX.png" alt="MCP Authorization Flow" width="500">
+</a>
+
+This diagram illustrates the flow of data and the role of authentication in ensuring secure interactions within the SMACK service.
+
+We encourage you to explore SMACK to understand the critical role of authentication and scalability in MCP-based interactions and to experience firsthand the enhancements brought by the MCP Engine.
+
+## Features
+
+- OAuth 2.1 authentication
+- Persistent message storage using PostgreSQL
+- Docker containerization for easy deployment
+
+## Prerequisites
+
+- Docker and Docker Compose
+- MCP Inspector (for testing and interaction)
+- npx (optional)
+
+## Quick Start
+
+### 1. Clone the repository and navigate to the examples/smack directory
+
+### 2. Start the service using Docker Compose:
+   ```bash
+   docker-compose up --build
+   ```
+   This will:
+   - Build and start the SMACK server on port 8000
+   - Start a PostgreSQL instance on port 5432
+   - Create necessary volumes for data persistence
+
+### 3. Connect to the service
+    You can use our proxy server to connect SMACK to your client.
+    Navigate to the proxy directory and build the main file:
+
+    ```bash
+    cd src/mcp/proxy
+    go build main.go
+    ```
+
+   There are multiple ways to interact with SMACK:
+   
+   #### a. Using the MCP Inspector
+   In a separate terminal run
+
+   ```bash
+   npx @modelcontextprotocol/inspector ./main <server-url>
+   ```
+   In this case the server url is http://localhost:8000/sse.
+
+   This will open the MCP inspector in your browser where you can list the tools and interact with the server.
+   
+   #### b. Using Claude Desktop
+   Create the config file if it doesn't exist:
+
+   ```bash
+   touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
+   ```
+   Add the following to the file:
+   ```json
+    {
+        "mcpServers": {
+        "smack_mcp_server": {
+        "command": "path/to/repo/mcp_engine/src/mcp/proxy/main",
+        "args": [
+            "http://localhost:8000/sse"
+        ]
+    }
+        }
+    }
+   ```
+
+   Save the file and restart Claude Desktop. You should now see the SMACK server in the list of available servers. 
+   You can now use Claude to send messages and list messages on SMACK.
+
+## Available Tools
+
+### `list_messages()`
+Retrieves all posted messages from the database.
+
+**Response Format:**
+```
+1. sender: message content
+2. sender: message content
+...
+```
+
+### `post_message(sender: str, message: str)`
+Posts a new message to the database.
+
+**Parameters:**
+- `sender`: The sender of the message
+- `message`: The text content you want to post
+
+**Response:**
+- Success: "Message posted successfully: '{message}'"
+- Failure: Error message if the post failed