@purplesquirrel/volcengine-mcp 1.0.0

package/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "chore(deps)"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "chore(ci)"

package/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run linter
+        run: npm run lint --if-present
+
+      - name: Run tests
+        run: npm test --if-present
+
+      - name: Build
+        run: npm run build --if-present

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Purple Squirrel Media
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io)
+[![Doubao](https://img.shields.io/badge/ByteDance-Doubao-00D1C1)](https://www.volcengine.com)
+[![CI](https://github.com/PurpleSquirrelMedia/volcengine-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/PurpleSquirrelMedia/volcengine-mcp/actions/workflows/ci.yml)
+
+# Volcano Engine MCP Server
+
+MCP server for ByteDance Volcano Engine (Doubao) integration with Claude Code. Enables Claude to delegate tasks to ByteDance's Doubao LLM models.
+
+## Features
+
+- **Text Generation** - Generate text using Doubao models
+- **Chat** - Multi-turn conversations with Doubao
+- **Embeddings** - Generate text embeddings for RAG and semantic search
+- **Model Listing** - List available Doubao models
+
+## Available Tools (4 total)
+
+| Tool | Description |
+|------|-------------|
+| `doubao_generate` | Generate text using Doubao models |
+| `doubao_chat` | Multi-turn chat with Doubao models |
+| `doubao_embeddings` | Generate text embeddings |
+| `doubao_list_models` | List available models |
+
+## Setup
+
+### 1. Get Volcano Engine API Key
+
+1. Sign up at [console.volcengine.com](https://console.volcengine.com)
+2. Complete real-name authentication (required)
+3. Navigate to: **Large Models** → **Volcano Ark** → **API Key Management**
+4. Create and copy your API key
+
+### 2. Install Dependencies
+
+```bash
+cd ~/mcp-servers/volcengine-mcp
+npm install
+```
+
+### 3. Add to Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "volcengine": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/Users/matthewkarsten/mcp-servers/volcengine-mcp/index.js"],
+      "env": {
+        "ARK_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `ARK_API_KEY` | Volcano Ark API key | Yes |
+| `VOLCENGINE_API_KEY` | Alternative API key env var | Yes (if ARK_API_KEY not set) |
+| `ARK_BASE_URL` | API base URL | No (defaults to Beijing region) |
+| `ARK_CHAT_MODEL` | Default chat model | No (defaults to doubao-pro-32k) |
+| `ARK_EMBEDDING_MODEL` | Default embedding model | No |
+
+## Available Models
+
+### Chat Models
+| Model ID | Description | Context |
+|----------|-------------|---------|
+| `doubao-pro-32k` | General purpose, large context | 32K |
+| `doubao-pro-4k` | General purpose, fast | 4K |
+| `doubao-lite-32k` | Lightweight, large context | 32K |
+| `doubao-lite-4k` | Lightweight, fast | 4K |
+| `doubao-seed-1-6-250615` | Latest with vision support | 32K |
+| `doubao-seed-1-6-flash-250615` | Fast thinking, low latency | 32K |
+| `doubao-seed-1-6-thinking-250615` | Deep reasoning | 32K |
+
+### Embedding Models
+| Model ID | Description | Dimensions |
+|----------|-------------|------------|
+| `doubao-embedding` | Text embeddings | 2560 |
+| `doubao-embedding-text-240715` | Latest embeddings | 2560 |
+
+## Architecture
+
+```
+Claude Code (Opus 4.5)
+         │
+         └──▶ Volcano Engine MCP Server
+                    │
+                    └──▶ Volcano Ark API
+                              │
+                              ├── Doubao Pro Models
+                              ├── Doubao Lite Models
+                              ├── Doubao Seed Models
+                              └── Embedding Models
+```
+
+## Usage Examples
+
+```
+User: Use Doubao to write a haiku about cloud computing
+
+Claude: [Uses doubao_generate tool]
+Result:
+{
+  "text": "Servers hum softly\nData flows through endless clouds\nDigital rain falls",
+  "model": "doubao-pro-32k",
+  "usage": { "prompt_tokens": 12, "completion_tokens": 18 }
+}
+```
+
+## Pricing
+
+ByteDance Volcano Engine offers competitive pricing:
+
+- **Free tier**: 500,000 tokens for individual users
+- **Doubao Pro**: ~0.0008 CNY / 1K tokens (~$0.0001 USD)
+- **Doubao Lite**: ~0.0003 CNY / 1K tokens
+
+## Multi-Agent Architecture
+
+This MCP server enables a multi-agent system:
+
+```
+Claude Code (Opus 4.5)
+         │
+         ├──▶ watsonx MCP Server (IBM Granite)
+         ├──▶ volcengine MCP Server (ByteDance Doubao)
+         └──▶ ibmz MCP Server (Key Protect HSM)
+```
+
+Claude can delegate different tasks to specialized models based on:
+- **Language**: Doubao excels at Chinese language tasks
+- **Latency**: Doubao Flash for real-time applications
+- **Reasoning**: Doubao Thinking for complex analysis
+- **Cost**: Doubao Lite for high-volume tasks
+
+## Files
+
+```
+volcengine-mcp/
+├── index.js        # MCP server implementation
+├── package.json    # Dependencies
+└── README.md       # This file
+```
+
+## Dependencies
+
+- `@modelcontextprotocol/sdk` - MCP SDK
+
+## Author
+
+Matthew Karsten
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,418 @@
+#!/usr/bin/env node
+
+/**
+ * Volcano Engine (ByteDance) MCP Server
+ *
+ * Provides integration with ByteDance's Doubao LLM models via the Volcano Ark API.
+ * Enables Claude to delegate tasks to Doubao models for text generation, chat, and embeddings.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+// Configuration from environment variables
+const ARK_API_KEY = process.env.ARK_API_KEY || process.env.VOLCENGINE_API_KEY;
+const ARK_BASE_URL = process.env.ARK_BASE_URL || 'https://ark.cn-beijing.volces.com/api/v3';
+
+// Default models
+const DEFAULT_CHAT_MODEL = process.env.ARK_CHAT_MODEL || 'doubao-pro-32k';
+const DEFAULT_EMBEDDING_MODEL = process.env.ARK_EMBEDDING_MODEL || 'doubao-embedding';
+
+/**
+ * Make authenticated request to Volcano Ark API
+ */
+async function arkRequest(endpoint, body, method = 'POST') {
+  if (!ARK_API_KEY) {
+    throw new Error('ARK_API_KEY or VOLCENGINE_API_KEY environment variable is required');
+  }
+
+  const response = await fetch(`${ARK_BASE_URL}${endpoint}`, {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${ARK_API_KEY}`,
+    },
+    body: method !== 'GET' ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Volcano Ark API error (${response.status}): ${error}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Generate text using Doubao models
+ */
+async function generateText(prompt, options = {}) {
+  const {
+    model = DEFAULT_CHAT_MODEL,
+    max_tokens = 2048,
+    temperature = 0.7,
+    top_p = 0.9,
+    system_prompt = null,
+  } = options;
+
+  const messages = [];
+
+  if (system_prompt) {
+    messages.push({ role: 'system', content: system_prompt });
+  }
+
+  messages.push({ role: 'user', content: prompt });
+
+  const response = await arkRequest('/chat/completions', {
+    model,
+    messages,
+    max_tokens,
+    temperature,
+    top_p,
+  });
+
+  return {
+    text: response.choices?.[0]?.message?.content || '',
+    model: response.model,
+    usage: response.usage,
+    finish_reason: response.choices?.[0]?.finish_reason,
+  };
+}
+
+/**
+ * Chat with Doubao models (multi-turn conversation)
+ */
+async function chat(messages, options = {}) {
+  const {
+    model = DEFAULT_CHAT_MODEL,
+    max_tokens = 2048,
+    temperature = 0.7,
+    top_p = 0.9,
+  } = options;
+
+  const response = await arkRequest('/chat/completions', {
+    model,
+    messages,
+    max_tokens,
+    temperature,
+    top_p,
+  });
+
+  return {
+    response: response.choices?.[0]?.message?.content || '',
+    model: response.model,
+    usage: response.usage,
+    finish_reason: response.choices?.[0]?.finish_reason,
+  };
+}
+
+/**
+ * Generate embeddings using Doubao embedding models
+ */
+async function generateEmbeddings(texts, options = {}) {
+  const { model = DEFAULT_EMBEDDING_MODEL } = options;
+
+  const input = Array.isArray(texts) ? texts : [texts];
+
+  const response = await arkRequest('/embeddings', {
+    model,
+    input,
+  });
+
+  return {
+    embeddings: response.data?.map(d => d.embedding) || [],
+    model: response.model,
+    usage: response.usage,
+    dimensions: response.data?.[0]?.embedding?.length || 0,
+  };
+}
+
+/**
+ * List available models (known Doubao models)
+ */
+function listModels() {
+  // Volcano Ark doesn't have a public model list API, so we return known models
+  return {
+    models: [
+      {
+        id: 'doubao-pro-32k',
+        name: 'Doubao Pro 32K',
+        description: 'General purpose model with 32K context window',
+        type: 'chat',
+        context_length: 32768,
+      },
+      {
+        id: 'doubao-pro-4k',
+        name: 'Doubao Pro 4K',
+        description: 'General purpose model with 4K context window',
+        type: 'chat',
+        context_length: 4096,
+      },
+      {
+        id: 'doubao-lite-32k',
+        name: 'Doubao Lite 32K',
+        description: 'Lightweight model with 32K context window',
+        type: 'chat',
+        context_length: 32768,
+      },
+      {
+        id: 'doubao-lite-4k',
+        name: 'Doubao Lite 4K',
+        description: 'Lightweight model with 4K context window',
+        type: 'chat',
+        context_length: 4096,
+      },
+      {
+        id: 'doubao-seed-1-6-250615',
+        name: 'Doubao Seed 1.6',
+        description: 'Latest Doubao model with vision support for agents',
+        type: 'chat',
+        context_length: 32768,
+      },
+      {
+        id: 'doubao-seed-1-6-flash-250615',
+        name: 'Doubao Seed 1.6 Flash',
+        description: 'Fast thinking model with low latency',
+        type: 'chat',
+        context_length: 32768,
+      },
+      {
+        id: 'doubao-seed-1-6-thinking-250615',
+        name: 'Doubao Seed 1.6 Thinking',
+        description: 'Deep reasoning model for complex tasks',
+        type: 'chat',
+        context_length: 32768,
+      },
+      {
+        id: 'doubao-embedding',
+        name: 'Doubao Embedding',
+        description: 'Text embedding model',
+        type: 'embedding',
+        dimensions: 2560,
+      },
+      {
+        id: 'doubao-embedding-text-240715',
+        name: 'Doubao Embedding Text',
+        description: 'Latest text embedding model',
+        type: 'embedding',
+        dimensions: 2560,
+      },
+    ],
+  };
+}
+
+// Create MCP Server
+const server = new Server(
+  {
+    name: 'volcengine-mcp-server',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Define available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'doubao_generate',
+        description: 'Generate text using ByteDance Doubao models. Use for text completion, content generation, and single-turn tasks.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            prompt: {
+              type: 'string',
+              description: 'The prompt to send to the model',
+            },
+            model: {
+              type: 'string',
+              description: 'Model ID (e.g., doubao-pro-32k, doubao-lite-4k, doubao-seed-1-6-250615)',
+              default: DEFAULT_CHAT_MODEL,
+            },
+            max_tokens: {
+              type: 'number',
+              description: 'Maximum tokens to generate',
+              default: 2048,
+            },
+            temperature: {
+              type: 'number',
+              description: 'Sampling temperature (0-1)',
+              default: 0.7,
+            },
+            system_prompt: {
+              type: 'string',
+              description: 'Optional system prompt to set context',
+            },
+          },
+          required: ['prompt'],
+        },
+      },
+      {
+        name: 'doubao_chat',
+        description: 'Have a multi-turn conversation with Doubao models. Supports conversation history.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            messages: {
+              type: 'array',
+              description: 'Array of chat messages with role (system/user/assistant) and content',
+              items: {
+                type: 'object',
+                properties: {
+                  role: {
+                    type: 'string',
+                    enum: ['system', 'user', 'assistant'],
+                  },
+                  content: {
+                    type: 'string',
+                  },
+                },
+                required: ['role', 'content'],
+              },
+            },
+            model: {
+              type: 'string',
+              description: 'Model ID to use',
+              default: DEFAULT_CHAT_MODEL,
+            },
+            max_tokens: {
+              type: 'number',
+              default: 2048,
+            },
+            temperature: {
+              type: 'number',
+              default: 0.7,
+            },
+          },
+          required: ['messages'],
+        },
+      },
+      {
+        name: 'doubao_embeddings',
+        description: 'Generate text embeddings using Doubao embedding models. Useful for semantic search and RAG.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            texts: {
+              type: 'array',
+              description: 'Array of texts to embed',
+              items: { type: 'string' },
+            },
+            model: {
+              type: 'string',
+              description: 'Embedding model ID',
+              default: DEFAULT_EMBEDDING_MODEL,
+            },
+          },
+          required: ['texts'],
+        },
+      },
+      {
+        name: 'doubao_list_models',
+        description: 'List available Doubao models from Volcano Engine',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'doubao_generate': {
+        const result = await generateText(args.prompt, {
+          model: args.model,
+          max_tokens: args.max_tokens,
+          temperature: args.temperature,
+          system_prompt: args.system_prompt,
+        });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case 'doubao_chat': {
+        const result = await chat(args.messages, {
+          model: args.model,
+          max_tokens: args.max_tokens,
+          temperature: args.temperature,
+        });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case 'doubao_embeddings': {
+        const result = await generateEmbeddings(args.texts, {
+          model: args.model,
+        });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case 'doubao_list_models': {
+        const result = listModels();
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error: ${error.message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('Volcano Engine MCP Server running on stdio');
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@purplesquirrel/volcengine-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for ByteDance Volcano Engine (Doubao) integration with Claude Code",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "volcano-engine",
+    "volcengine",
+    "bytedance",
+    "doubao",
+    "ai",
+    "llm"
+  ],
+  "author": "Matthew Karsten",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.0"
+  }
+}