@agentlify/mcp-server 2.0.0

package/docs/routing-strategies.md

@@ -0,0 +1,236 @@
+# Routing Strategies Explained
+
+Understanding how Agentlify selects models for your requests.
+
+---
+
+## Overview
+
+Agentlify routers use **intelligent routing** to automatically select the best model based on your optimization preferences.
+
+---
+
+## Three Main Strategies
+
+### 1. Cost-Optimized 💰
+
+**Best for:** High-volume applications, startups, cost-sensitive workloads
+
+**How it works:**
+
+- Prioritizes cheapest models that meet quality requirements
+- Routes to budget-friendly models (GPT-4o-mini, Claude Haiku, Gemini Flash)
+- Falls back to premium models only when necessary
+
+**Typical savings:** 50-60% vs. using only premium models
+
+**Example use cases:**
+
+- Customer support chatbots
+- Content moderation
+- Data classification
+- Simple Q&A systems
+
+---
+
+### 2. Quality-Optimized 🎯
+
+**Best for:** Content creation, complex reasoning, critical applications
+
+**How it works:**
+
+- Prioritizes highest-quality models (GPT-4, Claude Opus, Gemini Pro)
+- Considers cost as secondary factor
+- Ensures best possible responses
+
+**Typical cost:** 10-20% higher than cost-optimized, but still 30-40% savings vs. single provider
+
+**Example use cases:**
+
+- Professional content writing
+- Complex analysis
+- Research assistance
+- Creative applications
+
+---
+
+### 3. Speed-Optimized ⚡
+
+**Best for:** Real-time applications, user-facing chat, time-sensitive tasks
+
+**How it works:**
+
+- Prioritizes fastest models (GPT-4o-mini, Claude Haiku, Gemini Flash)
+- Minimizes latency over cost
+- Routes to geographically closer providers
+
+**Typical latency:** 200-500ms response times
+
+**Example use cases:**
+
+- Live chat applications
+- Real-time code completion
+- Interactive assistants
+- Gaming NPCs
+
+---
+
+## How Selection Works
+
+### 1. Request Analysis
+
+Router analyzes:
+
+- Message complexity
+- Expected response length
+- Required capabilities (vision, tools, etc.)
+
+### 2. Model Filtering
+
+Filters models based on:
+
+- Capabilities required
+- Budget constraints
+- Performance requirements
+
+### 3. Score Calculation
+
+Scores each model based on:
+
+```
+Score = (costWeight × costScore) +
+        (qualityWeight × qualityScore) +
+        (latencyWeight × latencyScore)
+```
+
+### 4. Model Selection
+
+Selects highest-scoring model and routes request
+
+---
+
+## Configuration
+
+### Dashboard
+
+Set weights when creating your router:
+
+- Cost Priority: 0-100%
+- Quality Priority: 0-100%
+- Speed Priority: 0-100%
+
+### Via API
+
+```javascript
+const router = await createRouter({
+  name: 'my-router',
+  routing_strategy: 'cost_optimized', // or "quality_optimized", "speed_optimized"
+});
+```
+
+---
+
+## Real-World Examples
+
+### Example 1: Cost-Optimized Chatbot
+
+**Configuration:**
+
+- Cost: 60%
+- Quality: 30%
+- Speed: 10%
+
+**Typical routing:**
+
+- Simple queries → GPT-4o-mini ($0.15/1M tokens)
+- Complex queries → Claude 3.5 Sonnet ($3/1M tokens)
+- Fallback → GPT-4 ($10/1M tokens)
+
+**Monthly cost:** $45 (vs. $100 with GPT-4 only)
+
+---
+
+### Example 2: Quality-Optimized Content
+
+**Configuration:**
+
+- Quality: 50%
+- Cost: 30%
+- Speed: 20%
+
+**Typical routing:**
+
+- All requests → GPT-4, Claude 3.5 Sonnet, or Gemini Pro
+- Never uses budget models unless premium models unavailable
+
+**Monthly cost:** $70 (vs. $100 with single provider)
+
+---
+
+### Example 3: Speed-Optimized Chat
+
+**Configuration:**
+
+- Speed: 50%
+- Quality: 30%
+- Cost: 20%
+
+**Typical routing:**
+
+- Most requests → GPT-4o-mini, Claude Haiku (< 500ms)
+- Complex requests → GPT-4-Turbo (< 1000ms)
+- Fallback → Claude 3.5 Sonnet
+
+**Average latency:** 350ms
+
+---
+
+## Best Practices
+
+### Start Cost-Optimized
+
+Begin with cost-optimized strategy, then adjust based on:
+
+- User feedback on quality
+- Actual latency requirements
+- Budget constraints
+
+### Monitor & Adjust
+
+Use dashboard analytics to:
+
+- Track model distribution
+- Measure average costs
+- Monitor response quality
+- Adjust weights accordingly
+
+### Use MCP Tools
+
+```
+User: "Optimize my router"
+
+AI Assistant:
+Current: Cost 40%, Quality 30%, Speed 30%
+Recommendation: Increase cost to 60%
+Potential savings: $25/month
+```
+
+---
+
+## Common Questions
+
+### Q: Can I force a specific model?
+
+**A:** Routers work best with all models. Forcing specific models defeats the purpose of intelligent routing.
+
+### Q: How often does routing change?
+
+**A:** Router selects best model for **each request** based on current conditions.
+
+### Q: What if my preferred model fails?
+
+**A:** Router automatically falls back to next-best model. No manual intervention needed.
+
+---
+
+For more configuration options, see [Router Configuration Guide](./router-configuration.md)

package/docs/sdk-javascript.md

@@ -0,0 +1,253 @@
+# JavaScript/TypeScript SDK Guide
+
+Complete guide for using Agentlify with JavaScript and TypeScript.
+
+---
+
+## Installation
+
+```bash
+npm install openai
+# Keep using OpenAI SDK!
+```
+
+---
+
+## Basic Setup
+
+```javascript
+const { OpenAI } = require('openai');
+
+const client = new OpenAI({
+  apiKey: process.env.AGENTLIFY_API_KEY, // mp_xxx
+  baseURL: `https://agentlify.co/api/router/${process.env.AGENTLIFY_ROUTER_ID}`,
+});
+```
+
+---
+
+## Chat Completions
+
+### Simple Request
+
+```javascript
+const response = await client.chat.completions.create({
+  messages: [{ role: 'user', content: 'What is JavaScript?' }],
+});
+
+console.log(response.choices[0].message.content);
+```
+
+### With System Prompt
+
+```javascript
+const response = await client.chat.completions.create({
+  messages: [
+    { role: 'system', content: 'You are a helpful coding assistant.' },
+    { role: 'user', content: 'Explain async/await' },
+  ],
+});
+```
+
+---
+
+## Streaming
+
+```javascript
+const stream = await client.chat.completions.create({
+  messages: [{ role: 'user', content: 'Tell me a story' }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || '');
+}
+```
+
+---
+
+## Function/Tool Calling
+
+```javascript
+const response = await client.chat.completions.create({
+  messages: [{ role: 'user', content: 'Get weather in NYC' }],
+  tools: [
+    {
+      type: 'function',
+      function: {
+        name: 'get_weather',
+        description: 'Get current weather',
+        parameters: {
+          type: 'object',
+          properties: {
+            location: { type: 'string' },
+          },
+          required: ['location'],
+        },
+      },
+    },
+  ],
+});
+
+if (response.choices[0].message.tool_calls) {
+  console.log('Tool calls:', response.choices[0].message.tool_calls);
+}
+```
+
+---
+
+## JSON Mode
+
+```javascript
+const response = await client.chat.completions.create({
+  messages: [
+    { role: 'system', content: 'You respond in JSON.' },
+    { role: 'user', content: 'Generate book info' },
+  ],
+  response_format: { type: 'json_object' },
+});
+
+const data = JSON.parse(response.choices[0].message.content);
+```
+
+---
+
+## TypeScript Example
+
+```typescript
+import { OpenAI } from 'openai';
+
+const client = new OpenAI({
+  apiKey: process.env.AGENTLIFY_API_KEY!,
+  baseURL: `https://agentlify.co/api/router/${process.env.AGENTLIFY_ROUTER_ID}`,
+});
+
+interface BookInfo {
+  title: string;
+  author: string;
+  year: number;
+}
+
+async function generateBook(): Promise<BookInfo> {
+  const response = await client.chat.completions.create({
+    messages: [
+      { role: 'system', content: 'Generate book info as JSON' },
+      { role: 'user', content: 'A sci-fi novel' },
+    ],
+    response_format: { type: 'json_object' },
+  });
+
+  return JSON.parse(response.choices[0].message.content);
+}
+```
+
+---
+
+## React/Next.js Example
+
+```typescript
+'use client';
+
+import { useState } from 'react';
+import { OpenAI } from 'openai';
+
+const client = new OpenAI({
+  apiKey: process.env.NEXT_PUBLIC_AGENTLIFY_API_KEY!,
+  baseURL: `https://agentlify.co/api/router/${process.env.NEXT_PUBLIC_AGENTLIFY_ROUTER_ID}`,
+  dangerouslyAllowBrowser: true  // For client-side
+});
+
+export default function ChatComponent() {
+  const [messages, setMessages] = useState([]);
+  const [input, setInput] = useState('');
+
+  const sendMessage = async () => {
+    const newMessages = [...messages, { role: 'user', content: input }];
+    setMessages(newMessages);
+
+    const response = await client.chat.completions.create({
+      messages: newMessages
+    });
+
+    setMessages([
+      ...newMessages,
+      { role: 'assistant', content: response.choices[0].message.content }
+    ]);
+  };
+
+  return (
+    <div>
+      {messages.map((msg, i) => (
+        <div key={i}>{msg.role}: {msg.content}</div>
+      ))}
+      <input value={input} onChange={(e) => setInput(e.target.value)} />
+      <button onClick={sendMessage}>Send</button>
+    </div>
+  );
+}
+```
+
+---
+
+## Environment Variables
+
+```bash
+# .env.local
+AGENTLIFY_API_KEY=mp_your_api_key
+AGENTLIFY_ROUTER_ID=your_router_id
+```
+
+---
+
+## Error Handling
+
+```javascript
+try {
+  const response = await client.chat.completions.create({
+    messages: [{ role: 'user', content: 'Hello' }],
+  });
+} catch (error) {
+  if (error.status === 401) {
+    console.error('Invalid API key');
+  } else if (error.status === 429) {
+    console.error('Rate limit exceeded');
+  } else {
+    console.error('Error:', error.message);
+  }
+}
+```
+
+---
+
+## Cost Tracking
+
+```javascript
+const response = await client.chat.completions.create({
+  messages: [{ role: 'user', content: 'Hello' }],
+});
+
+// Access Agentlify metadata
+console.log('Cost:', response._meta?.cost);
+console.log('Model used:', response._meta?.modelUsed);
+console.log('Latency:', response._meta?.latency, 'ms');
+```
+
+---
+
+## Framework Integration
+
+Works with all frameworks:
+
+- ✅ Next.js
+- ✅ React
+- ✅ Express
+- ✅ Nest.js
+- ✅ LangChain.js
+- ✅ LlamaIndex
+- ✅ Vercel AI SDK
+
+**Same SDK, same code!**
+
+---
+
+For more examples, see [Examples folder](./examples/)

package/docs/sdk-python.md

@@ -0,0 +1,52 @@
+# Agentlify Python SDK Reference
+
+Use the Python SDK to call routers and agents with an OpenAI-compatible interface.
+
+## Install
+
+```bash
+pip install agentlify
+```
+
+## Initialize
+
+```python
+from agentlify import Agentlify
+
+client = Agentlify(api_key="mp_your_api_key")
+```
+
+## Router Completion
+
+```python
+response = client.routers.create_completion(
+    router="your-router-id",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+print(response["choices"][0]["message"]["content"])
+```
+
+## Agent Completion
+
+```python
+response = client.chat.completions.create(
+    model="agent:your-agent-id",
+    messages=[{"role": "user", "content": "Summarize this"}],
+)
+print(response["choices"][0]["message"]["content"])
+```
+
+## Manual Tool Call Continuation
+
+If an agent response includes `tool_calls`, execute them in your app and send back:
+
+- the assistant message containing `tool_calls`
+- one `role: "tool"` message per tool result with matching `tool_call_id`
+
+Then call the same `agent:` model again to continue execution.
+
+## Notes
+
+- Keep API keys in environment variables.
+- Pass only schema-valid JSON arguments for tools.
+- For production retries, use idempotency keys when your webhook tools support them.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@agentlify/mcp-server",
+  "version": "2.0.0",
+  "description": "Model Context Protocol server for Agentlify - enables AI assistants to integrate Agentlify",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "agentlify-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "agentlify",
+    "ai",
+    "llm",
+    "openai",
+    "anthropic",
+    "claude",
+    "gpt"
+  ],
+  "author": "Agentlify",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}