feat: adds mcp functionality to fullstack app (#670)

* feat: adds mcp functionality to fullstack app

Signed-off-by: Anthony D. Mays <[email protected]>

* chore: refactors authenticateApiKey into shared util

Signed-off-by: Anthony D. Mays <[email protected]>

* chore: remove header logging

Signed-off-by: Anthony D. Mays <[email protected]>

* chore: updates claude desktop config example

Signed-off-by: Anthony D. Mays <[email protected]>

---------

Signed-off-by: Anthony D. Mays <[email protected]>

Author: anthonydmays

lib/javascript/fullstack_demo/.env.example

@@ -1,4 +1,8 @@
 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=Your Next Public Clerk Publishable Key here
 CLERK_SECRET_KEY=Your Clerk Secret Key here
 DB_TYPE=in-memory
-NEXT_PUBLIC_API_URL=http://localhost:3000
+NEXT_PUBLIC_API_URL=http://localhost:3000
+
+# MCP Server Configuration
+MCP_API_KEY=your-secret-mcp-api-key-here
+MCP_DEFAULT_USER_ID=mcp-user

lib/javascript/fullstack_demo/mcp-server/.env.example

@@ -0,0 +1,6 @@
+# Environment Configuration
+TODO_API_BASE_URL=http://localhost:3000/api/mcp
+MCP_API_KEY=your-secret-mcp-api-key-here
+
+# Optional: Database connection for direct DB access
+DATABASE_URL=your_database_url_here

lib/javascript/fullstack_demo/mcp-server/.gitignore

@@ -0,0 +1,26 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# Environment files
+.env
+.env.local
+.env.production
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+logs/
+*.log

lib/javascript/fullstack_demo/mcp-server/AUTHENTICATION.md

@@ -0,0 +1,123 @@
+# Authentication Setup for Claude Desktop
+
+## Quick Setup Guide
+
+### 1. Configure Your Todo App
+
+Add these environment variables to your todo app's `.env` file:
+
+```bash
+# Add to /lib/javascript/fullstack_demo/.env
+MCP_API_KEY=your-secret-mcp-api-key-here
+MCP_DEFAULT_USER_ID=your-user-id-here
+```
+
+**Generate a secure API key:**
+```bash
+# Generate a random API key
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+### 2. Configure MCP Server
+
+Create/update the MCP server's `.env` file:
+
+```bash
+# /lib/javascript/fullstack_demo/mcp-server/.env
+TODO_API_BASE_URL=http://localhost:3000/api/mcp
+MCP_API_KEY=your-secret-mcp-api-key-here
+```
+
+**Use the same API key in both files!**
+
+### 3. Configure Claude Desktop
+
+Update your Claude Desktop config file:
+
+**Location:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+
+```json
+{
+  "mcpServers": {
+    "todo-mcp-server": {
+      "command": "node",
+      "args": ["/full/path/to/your/mcp-server/dist/index.js"],
+      "env": {
+        "TODO_API_BASE_URL": "http://localhost:3000/api/mcp",
+        "MCP_API_KEY": "your-secret-mcp-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### 4. Build and Test
+
+1. **Start your todo app:**
+   ```bash
+   cd /lib/javascript/fullstack_demo
+   npm run dev
+   ```
+
+2. **Build the MCP server:**
+   ```bash
+   cd /lib/javascript/fullstack_demo/mcp-server
+   npm run build
+   ```
+
+3. **Restart Claude Desktop** to pick up the new configuration
+
+### 5. Test Authentication
+
+In Claude Desktop, try:
+```
+Can you show me my todos?
+```
+
+If authentication works, you should see your todos or an empty list.
+
+## Troubleshooting
+
+### "Unauthorized - Invalid API Key"
+- Check that the API key is the same in both `.env` files
+- Ensure the MCP server environment variables are set correctly
+- Restart Claude Desktop after config changes
+
+### "Cannot connect to API"
+- Verify your todo app is running on the correct port
+- Check that the `TODO_API_BASE_URL` points to the MCP endpoints (`/api/mcp`)
+- Ensure firewalls aren't blocking the connection
+
+### "User not found" errors
+- Set `MCP_DEFAULT_USER_ID` to a valid user ID from your system
+- For development, you can use any string like "test-user"
+
+## Security Notes
+
+⚠️ **Important for Production:**
+
+1. **Keep API keys secret** - Never commit them to version control
+2. **Use environment variables** - Don't hardcode keys in your config
+3. **Rotate keys regularly** - Generate new API keys periodically
+4. **Limit scope** - Consider implementing user-specific API keys
+5. **Use HTTPS** - In production, always use HTTPS for API communication
+
+## Alternative: User-Specific Authentication
+
+For multiple users, you can extend the authentication to map API keys to specific users:
+
+```typescript
+// In your API route
+const userKeyMap = {
+  'api-key-1': 'user-1',
+  'api-key-2': 'user-2',
+  // etc.
+};
+
+function authenticateApiKey(request: Request): string | null {
+  const apiKey = request.headers.get('X-API-Key');
+  return userKeyMap[apiKey] || null;
+}
+```
+
+This allows each Claude Desktop user to have their own API key and access their own todos.

lib/javascript/fullstack_demo/mcp-server/DEPLOYMENT.md

@@ -0,0 +1,124 @@
+# Todo MCP Server Deployment Guide
+
+## Quick Start
+
+1. **Build the server**:
+   ```bash
+   cd mcp-server
+   npm install
+   npm run build
+   ```
+
+2. **Configure environment**:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your configuration
+   ```
+
+3. **Test the server**:
+   ```bash
+   node test.mjs
+   ```
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+Add this to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "todo-mcp-server": {
+      "command": "node",
+      "args": ["/path/to/your/mcp-server/dist/index.js"],
+      "env": {
+        "TODO_API_BASE_URL": "http://localhost:3000/api"
+      }
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+For other MCP-compatible clients, use the stdio transport with:
+- **Command**: `node`
+- **Args**: `["/path/to/mcp-server/dist/index.js"]`
+- **Environment**: Set `TODO_API_BASE_URL` to your API base URL
+
+## Environment Variables
+
+| Variable            | Description                         | Default                     | Required |
+| ------------------- | ----------------------------------- | --------------------------- | -------- |
+| `TODO_API_BASE_URL` | Base URL of the Todo API            | `http://localhost:3000/api` | Yes      |
+| `CLERK_SECRET_KEY`  | Clerk secret key for authentication | -                           | Optional |
+
+## Usage Examples
+
+Once configured with an MCP client, you can use these tools:
+
+### Get All Todos
+```
+Can you show me all my todos?
+```
+
+### Create a Todo
+```
+Create a new todo: "Learn about MCP servers"
+```
+
+### Update a Todo
+```
+Update todo ID 1 to mark it as completed
+```
+
+### Get Statistics
+```
+Show me my todo statistics
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Module not found errors**:
+   - Ensure you've run `npm run build`
+   - Check that the path in your MCP client config is correct
+
+2. **API connection errors**:
+   - Verify the Todo app is running on the correct port
+   - Check the `TODO_API_BASE_URL` environment variable
+   - Ensure the API endpoints are accessible
+
+3. **Authentication errors**:
+   - For production use, configure proper authentication
+   - Set the `CLERK_SECRET_KEY` if using Clerk authentication
+
+### Debug Mode
+
+Run the server in development mode to see detailed logs:
+```bash
+npm run dev
+```
+
+## Security Considerations
+
+⚠️ **Important**: This MCP server is currently configured for development use. For production deployment:
+
+1. **Authentication**: Implement proper API authentication
+2. **HTTPS**: Use HTTPS for API communication
+3. **Rate Limiting**: Implement rate limiting to prevent abuse
+4. **Input Validation**: Add additional input validation and sanitization
+5. **Error Handling**: Avoid exposing sensitive information in error messages
+
+## API Compatibility
+
+This MCP server is designed to work with the Todo app's REST API:
+
+- `GET /api/todos` - Get all todos
+- `POST /api/todos` - Create a new todo
+- `PATCH /api/todos/{id}` - Update a todo
+- `DELETE /api/todos/{id}` - Delete a todo
+
+Ensure your Todo app implements these endpoints for full compatibility.