wip: Add new unified mcp implementation

.mcp.json

@@ -1,5 +1,9 @@
 {
   "mcpServers": {
+    "llmtxt.dev": {
+      "type": "sse",
+      "url": "https://mcp.llmtxt.dev/sse"
+    },
     "deepwiki": {
       "type": "http",
       "url": "https://mcp.deepwiki.com/mcp"
@@ -16,6 +20,25 @@
       ],
       "env": {}
     },
+    "search": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-brave-search"
+      ],
+      "env": {}
+     },
+    "gitingest-mcp": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/puravparab/gitingest-mcp",
+        "gitingest-mcp"
+      ],
+      "env": {}
+    },
     "firecrawl": {
       "type": "stdio",
       "command": "npx",
@@ -24,6 +47,24 @@
         "firecrawl-mcp"
       ],
       "env": {}
+    },
+    "context7": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp"
+      ],
+      "env": {}
+    },
+    "typespec-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-server-typespec@latest"
+      ],
+      "env": {}
     }
   }
 }

docker-compose.yml

@@ -15,6 +15,7 @@ include:
   - ./blob-store/docker-compose-ha.yml
   - ./hasura/docker-compose.yml
   - ./analytics/docker-compose.yml
+  - ./mcp/docker-compose.yml
   # - ./code-interpreter/docker-compose.yml
   # - ./embedding-service/docker-compose.yml
 

gateway/traefik.yml.template

@@ -153,6 +153,17 @@ http:
       service: service-analytics
       priority: 1
 
+    # MCP (Model Context Protocol) Server
+    mcp:
+      entryPoints:
+        - web
+      rule: PathPrefix(`/mcp`)
+      middlewares:
+        - corsHeaders
+        - mcp-strip-prefix
+      service: service-mcp
+      priority: 3
+
   middlewares:
     corsHeaders:
       headers:
@@ -226,6 +237,12 @@ http:
         regex: "^/analytics$"
         replacement: "/analytics/"
 
+    mcp-strip-prefix:
+      stripprefix:
+        prefixes:
+          - /mcp
+        forceSlash: false
+
   services:
     service-agents-api:
       loadBalancer:
@@ -251,6 +268,12 @@ http:
         servers:
           - url: $ANALYTICS_URL
 
+    service-mcp:
+      loadBalancer:
+        passHostHeader: false
+        servers:
+          - url: http://mcp:3000
+
 experimental:
   localPlugins:
     jwt:

mcp/.gitignore

@@ -0,0 +1,64 @@
+# Build outputs
+dist/
+build/
+*.tsbuildinfo
+
+# Dependencies
+node_modules/
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids/
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage directory used by tools like istanbul
+coverage/
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.temp
+.cache/
+
+# Backup files
+*.bak
+*.backup
+tools.bak/
+
+# Jest coverage
+coverage/
+
+# TypeScript cache
+*.tsbuildinfo

mcp/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "julep-mcp": {
+      "type": "stdio",
+      "command": "npm",
+      "args": [
+        "start"
+      ],
+      "env": {
+        "JULEP_API_KEY": "your-julep-api-key-here"
+      }
+    }
+  }
+}

mcp/AGENTS.md

@@ -0,0 +1,146 @@
+# AGENTS.md - mcp
+
+This directory contains the Unified MCP (Model Context Protocol) Server that provides documentation search and SDK access for Julep.
+
+## Key Uses
+- Bash commands:
+  - `cd mcp`
+  - `npm install`
+  - `npm run dev` (stdio mode)
+  - `npm run dev:http` (HTTP mode)
+  - `docker-compose up mcp`
+- Core files:
+  - `src/index.ts` - Entry point with transport detection
+  - `src/server.ts` - Core MCP server implementation
+  - `src/http-transport.ts` - HTTP transport for service deployment
+  - `docker-compose.yml` - Container deployment configuration
+  - `Dockerfile` - Multi-stage build configuration
+- Configuration guidelines:
+  - Set `JULEP_API_KEY` for SDK access
+  - Configure `AGENTS_API_URL` for backend connectivity
+  - HTTP server runs on port 3000 by default
+  - Accessible via gateway at `/mcp` path
+- Testing instructions:
+  - Health check: `curl http://localhost/mcp/health`
+  - Server info: `curl http://localhost/mcp/`
+  - Use test script: `./scripts/test-server.sh`
+- Repository etiquette:
+  - Don't commit API keys or credentials
+  - Update CLAUDE.md when adding features
+  - Maintain client compatibility
+- Developer environment:
+  - Node.js 20+ required
+  - TypeScript for development
+  - Docker for production deployment
+- Unexpected behaviors:
+  - Client auto-detection based on environment
+  - Schema transformations for compatibility
+  - Documentation tools always available
+
+## Service Overview
+
+The MCP service provides a unified interface for:
+1. **Documentation Search**: Query Julep documentation via Trieve/Mintlify
+2. **SDK Operations**: Full access to Julep SDK with 100+ tools
+3. **Client Compatibility**: Automatic adaptations for different MCP clients
+
+## Architecture
+
+- **Transport Modes**:
+  - stdio: Direct CLI usage with environment auth
+  - HTTP: Service deployment behind Traefik proxy
+- **Authentication**:
+  - Environment variable: `JULEP_API_KEY`
+  - Headers in HTTP mode: Authorization token
+- **Client Support**:
+  - Auto-detection for major MCP clients
+  - Schema transformations for compatibility
+  - Capability-based feature flags
+
+## Key Components
+
+### Server Core
+- **UnifiedMcpServer**: Main server class with tool management
+- **Tool Loading**: Dynamic discovery from SDK endpoints
+- **Client Detection**: Automatic identification and adaptation
+- **Error Handling**: Detailed messages with guidance
+
+### HTTP Transport
+- **Express Server**: RESTful API for MCP protocol
+- **Health Checks**: Monitoring endpoints
+- **CORS Support**: Cross-origin request handling
+- **Request Routing**: Protocol messages over HTTP POST
+
+### Tool Categories
+- **Documentation Tools**: Always available, no auth required
+- **SDK Tools**: Require authentication, full API access
+- **Tool Transformations**: Client-specific adaptations
+
+## Integration Points
+
+- **Traefik Gateway**: Routes `/mcp` traffic to service
+- **Docker Network**: Connects to `julep_default` network
+- **Agents API**: Direct access for SDK operations
+- **Mintlify/Trieve**: Documentation search backend
+
+## Development Workflow
+
+1. **Local Development**:
+   ```bash
+   npm install
+   npm run dev  # stdio mode
+   npm run dev:http  # HTTP mode
+   ```
+
+2. **Docker Development**:
+   ```bash
+   docker-compose up --build mcp
+   ```
+
+3. **Testing**:
+   ```bash
+   ./scripts/test-server.sh
+   npm test
+   ```
+
+## Environment Variables
+
+- `JULEP_API_KEY`: API key for SDK authentication
+- `AGENTS_API_URL`: Backend API URL (default: http://agents-api:8080)
+- `TRANSPORT`: Transport mode (stdio/http)
+- `PORT`: HTTP server port (default: 3000)
+- `MCP_CLIENT`: Override client detection
+
+## Monitoring & Debugging
+
+- Health endpoint: `/health`
+- Server info: `/`
+- Console logs for debugging
+- Client detection info on startup
+
+## Common Tasks
+
+1. **Add New Client Support**:
+   - Update `compat/clients.ts`
+   - Add detection logic
+   - Create config template
+   - Test transformations
+
+2. **Update SDK Tools**:
+   - Modify `tools/sdk/endpoints.ts`
+   - Run build and test
+   - Update documentation
+
+3. **Debug Client Issues**:
+   - Check detection logs
+   - Verify transformations
+   - Test with specific client
+
+## Security Notes
+
+- API keys handled securely
+- No credential logging
+- HTTPS via Traefik proxy
+- Container runs as non-root user
+
+# AIDEV-NOTE: MCP service provides unified access to docs and SDK with client compatibility

mcp/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

mcp/Dockerfile

@@ -0,0 +1,50 @@
+# Multi-stage build for Julep Unified MCP Server
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+COPY tsconfig.json ./
+
+# Install dependencies
+RUN npm ci
+
+# Copy source code
+COPY src/ ./src/
+COPY build.sh ./
+
+# Build the application
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Install production dependencies only
+COPY package*.json ./
+RUN npm ci --only=production && npm cache clean --force
+
+# Copy built application
+COPY --from=builder /app/dist ./dist
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001
+
+# Switch to non-root user
+USER nodejs
+
+# Expose port for HTTP transport
+EXPOSE 3000
+
+# Default to HTTP transport for service mode
+ENV TRANSPORT=http
+ENV PORT=3000
+
+# Entry point
+ENTRYPOINT ["node", "dist/index.js"]
+
+# Default command (can be overridden)
+CMD ["--transport", "http", "--port", "3000"]