@erickstryck/simple-vision-mcp 1.0.0

package/.env.example

@@ -0,0 +1,8 @@
+# Required
+VISION_API_KEY=your-api-key-here
+VISION_BASE_URL=https://api.example.com/v1
+VISION_MODEL=your-vision-model
+
+# Optional
+VISION_MAX_TOKENS=4096
+VISION_TIMEOUT=120

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+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,274 @@
+# Simple Vision MCP
+
+A lightweight, focused Model Context Protocol (MCP) server designed specifically for image analysis using OpenAI-compatible APIs. Built with TypeScript and the MCP SDK.
+
+## Motivation
+
+When working with AI coding agents that don't natively support vision capabilities, you often need a reliable way to analyze images. Many existing MCP vision servers are tightly coupled to specific providers (like OpenRouter or OpenAI) or come with unnecessary complexity.
+
+**Simple Vision MCP** was created to solve a specific problem: enabling any OpenAI-compatible API endpoint to function as a vision analysis backend. It focuses on doing one thing exceptionally well - analyzing images - while remaining flexible enough to work with any OpenAI-compatible provider.
+
+### The Problem We Solved
+
+During setup, we encountered several issues:
+1. Many vision MCP servers only support specific providers (OpenRouter, OpenAI, etc.)
+2. Container-based solutions had stdio communication issues
+3. Python-based servers had dependency conflicts
+4. Existing solutions were overly complex for the basic need
+
+Simple Vision MCP addresses these by:
+- Supporting **any** OpenAI-compatible API endpoint
+- Running as a native Node.js process (no containers needed)
+- Minimal, focused codebase that's easy to debug and maintain
+- Zero external dependencies beyond the MCP SDK
+
+## Features
+
+- **OpenAI-Compatible**: Works with any API that follows the OpenAI chat completions format
+- **Single Tool Focus**: One purpose - image analysis done right
+- **TypeScript**: Full type safety and modern JavaScript
+- **Minimal Dependencies**: Only essential dependencies
+- **STDIO Communication**: Native MCP protocol support
+- **Configurable**: Full control via environment variables
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18 or higher
+- An OpenAI-compatible API endpoint with vision capabilities
+
+### From Source
+
+```bash
+git clone https://github.com/yourusername/simple-vision-mcp.git
+cd simple-vision-mcp
+npm install
+npm run build
+```
+
+### Global Installation
+
+```bash
+npm install -g simple-vision-mcp
+```
+
+## Configuration
+
+Simple Vision MCP is configured entirely via environment variables. Create a `.env` file or export variables directly:
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `VISION_API_KEY` | Your API key | Yes | - |
+| `VISION_BASE_URL` | API endpoint base URL | Yes | `https://api.openai.com/v1` |
+| `VISION_MODEL` | Model name for vision | Yes | `gpt-4o-mini` |
+| `VISION_MAX_TOKENS` | Max response tokens | No | `4096` |
+| `VISION_TIMEOUT` | Request timeout (seconds) | No | `120` |
+
+### Example .env File
+
+```env
+VISION_API_KEY=your-api-key-here
+VISION_BASE_URL=https://your-custom-endpoint.com/api/v1
+VISION_MODEL=Qwen3.5-4B-AWQ
+VISION_MAX_TOKENS=4096
+VISION_TIMEOUT=120
+```
+
+## Usage
+
+### Running the Server
+
+```bash
+# Using the built version
+npm start
+
+# Or directly with node
+node dist/index.js
+
+# With environment variables
+VISION_API_KEY=your-key VISION_BASE_URL=https://api.example.com/v1 VISION_MODEL=your-model node dist/index.js
+```
+
+### OpenCode Configuration
+
+Add to your `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "vision": {
+      "type": "local",
+      "command": ["node", "/path/to/simple-vision-mcp/dist/index.js"],
+      "env": {
+        "VISION_API_KEY": "your-api-key",
+        "VISION_BASE_URL": "https://your-endpoint.com/api/v1",
+        "VISION_MODEL": "your-vision-model"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+### Claude Desktop Configuration
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "vision": {
+      "command": "node",
+      "args": ["/path/to/simple-vision-mcp/dist/index.js"],
+      "env": {
+        "VISION_API_KEY": "your-api-key",
+        "VISION_BASE_URL": "https://your-endpoint.com/api/v1",
+        "VISION_MODEL": "your-vision-model"
+      }
+    }
+  }
+}
+```
+
+### Cursor Configuration
+
+Add to your Cursor MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "vision": {
+      "command": "node",
+      "args": ["/path/to/simple-vision-mcp/dist/index.js"],
+      "env": {
+        "VISION_API_KEY": "your-api-key",
+        "VISION_BASE_URL": "https://your-endpoint.com/api/v1",
+        "VISION_MODEL": "your-vision-model"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### analyze_image
+
+Analyzes an image and returns a detailed description.
+
+**Parameters:**
+
+| Parameter | Type | Description | Required |
+|-----------|------|-------------|----------|
+| `image_path` | string | Path to the image file | Yes |
+| `prompt` | string | Custom analysis prompt | No |
+
+**Default Prompt:** "Describe this image in detail, including objects, text, colors, composition, and any notable features."
+
+**Example:**
+
+```json
+{
+  "name": "analyze_image",
+  "arguments": {
+    "image_path": "/path/to/image.png",
+    "prompt": "What objects are in this image?"
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "The image shows a red square with..."
+    }
+  ]
+}
+```
+
+## Supported Image Formats
+
+- PNG (.png)
+- JPEG (.jpg, .jpeg)
+- GIF (.gif)
+- WebP (.webp)
+- BMP (.bmp)
+
+## Development
+
+### Project Structure
+
+```
+simple-vision-mcp/
+├── src/
+│   ├── config/
+│   │   └── index.ts          # Configuration loading
+│   ├── services/
+│   │   └── visionService.ts  # Vision API client
+│   ├── tools/
+│   │   └── analyzeImage.ts   # MCP tool definition
+│   ├── utils/
+│   │   └── imageProcessor.ts # Image processing utilities
+│   └── index.ts              # Main entry point
+├── tests/
+│   ├── config.test.ts
+│   ├── imageProcessor.test.ts
+│   └── visionService.test.ts
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+# Run tests once
+npm test
+
+# Watch mode
+npm run test:watch
+```
+
+### Design Principles
+
+1. **Single Responsibility**: Each module has one clear purpose
+2. **Dependency Injection**: Services receive dependencies via constructor
+3. **Functional Core**: Business logic is pure and testable
+4. **Explicit over Implicit**: Clear types and function signatures
+
+## Troubleshooting
+
+### "VISION_API_KEY environment variable is required"
+
+Ensure you've set the `VISION_API_KEY` environment variable before starting the server.
+
+### "Unsupported image format"
+
+The image format is not supported. Ensure your image is PNG, JPEG, GIF, WebP, or BMP format.
+
+### "Vision API error: 401"
+
+Authentication failed. Verify your API key is correct and has access to vision capabilities.
+
+### "Vision API error: 4xx/5xx"
+
+Check your `VISION_BASE_URL` is correct and the API endpoint is accessible.
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+Contributions welcome! Please feel free to submit a Pull Request.

package/dist/config/index.d.ts

@@ -0,0 +1,9 @@
+export interface ServerConfig {
+    apiKey: string;
+    baseUrl: string;
+    model: string;
+    maxTokens: number;
+    timeout: number;
+}
+export declare function loadConfig(): ServerConfig;
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,UAAU,IAAI,YAAY,CAYzC"}

package/dist/config/index.js

@@ -0,0 +1,12 @@
+export function loadConfig() {
+    const apiKey = process.env.VISION_API_KEY || process.env.OPENAI_API_KEY || '';
+    const baseUrl = process.env.VISION_BASE_URL || process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1';
+    const model = process.env.VISION_MODEL || process.env.OPENAI_MODEL || 'gpt-4o-mini';
+    const maxTokens = parseInt(process.env.VISION_MAX_TOKENS || '4096', 10);
+    const timeout = parseInt(process.env.VISION_TIMEOUT || '120', 10);
+    if (!apiKey) {
+        throw new Error('VISION_API_KEY or OPENAI_API_KEY environment variable is required');
+    }
+    return { apiKey, baseUrl, model, maxTokens, timeout };
+}
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,UAAU;IACxB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC;IAC9E,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,2BAA2B,CAAC;IAC1G,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,aAAa,CAAC;IACpF,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,MAAM,EAAE,EAAE,CAAC,CAAC;IACxE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,KAAK,EAAE,EAAE,CAAC,CAAC;IAElE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AACxD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,46 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { loadConfig } from './config/index.js';
+import { VisionService } from './services/visionService.js';
+import { createAnalyzeImageTool } from './tools/analyzeImage.js';
+class VisionMCPServer {
+    server;
+    visionService;
+    constructor() {
+        const config = loadConfig();
+        this.visionService = new VisionService(config);
+        this.server = new Server({
+            name: 'simple-vision-mcp',
+            version: '1.0.0',
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, () => ({
+            tools: [createAnalyzeImageTool(this.visionService)],
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            if (name === 'analyze_image') {
+                const tool = createAnalyzeImageTool(this.visionService);
+                return await tool.handler(args);
+            }
+            throw new Error(`Unknown tool: ${name}`);
+        });
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+    }
+}
+const server = new VisionMCPServer();
+server.run().catch((error) => {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AACnG,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,MAAM,eAAe;IACX,MAAM,CAAS;IACf,aAAa,CAAgB;IAErC;QACE,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;QAC5B,IAAI,CAAC,aAAa,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;QAE/C,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CACtB;YACE,IAAI,EAAE,mBAAmB;YACzB,OAAO,EAAE,OAAO;SACjB,EACD;YACE,YAAY,EAAE;gBACZ,KAAK,EAAE,EAAE;aACV;SACF,CACF,CAAC;QAEF,IAAI,CAAC,aAAa,EAAE,CAAC;IACvB,CAAC;IAEO,aAAa;QACnB,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,GAAG,EAAE,CAAC,CAAC;YAC3D,KAAK,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;SACpD,CAAC,CAAC,CAAC;QAEJ,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACrE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;YAEjD,IAAI,IAAI,KAAK,eAAe,EAAE,CAAC;gBAC7B,MAAM,IAAI,GAAG,sBAAsB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;gBACxD,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,IAA+C,CAAC,CAAC;YAC7E,CAAC;YAED,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;QAC3C,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAG;QACP,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAC7C,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;CACF;AAED,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;AACrC,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC3B,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;IAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/services/visionService.d.ts

@@ -0,0 +1,20 @@
+import { ServerConfig } from '../config/index.js';
+export interface VisionRequest {
+    imageDataUrl: string;
+    prompt: string;
+    maxTokens: number;
+}
+export interface VisionResponse {
+    content: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+export declare class VisionService {
+    private readonly config;
+    constructor(config: ServerConfig);
+    analyze(request: VisionRequest): Promise<VisionResponse>;
+}
+//# sourceMappingURL=visionService.d.ts.map

package/dist/services/visionService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visionService.d.ts","sourceRoot":"","sources":["../../src/services/visionService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE;QACN,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,YAAY;IAE3C,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;CA6C/D"}

package/dist/services/visionService.js

@@ -0,0 +1,44 @@
+export class VisionService {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async analyze(request) {
+        const { imageDataUrl, prompt, maxTokens } = request;
+        const response = await fetch(`${this.config.baseUrl}/chat/completions`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.config.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: this.config.model,
+                messages: [
+                    {
+                        role: 'user',
+                        content: [
+                            { type: 'text', text: prompt },
+                            { type: 'image_url', image_url: { url: imageDataUrl } },
+                        ],
+                    },
+                ],
+                max_tokens: maxTokens,
+            }),
+        });
+        if (!response.ok) {
+            const errorBody = await response.text();
+            throw new Error(`Vision API error: ${response.status} - ${errorBody}`);
+        }
+        const data = await response.json();
+        const content = data.choices[0]?.message?.content || '';
+        return {
+            content,
+            usage: data.usage ? {
+                promptTokens: data.usage.prompt_tokens,
+                completionTokens: data.usage.completion_tokens,
+                totalTokens: data.usage.total_tokens,
+            } : undefined,
+        };
+    }
+}
+//# sourceMappingURL=visionService.js.map

package/dist/services/visionService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visionService.js","sourceRoot":"","sources":["../../src/services/visionService.ts"],"names":[],"mappings":"AAiBA,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,MAAoB;QAApB,WAAM,GAAN,MAAM,CAAc;IAAG,CAAC;IAErD,KAAK,CAAC,OAAO,CAAC,OAAsB;QAClC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;QAEpD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,mBAAmB,EAAE;YACtE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,eAAe,EAAE,UAAU,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE;aAChD;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;gBACxB,QAAQ,EAAE;oBACR;wBACE,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE;4BACP,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;4BAC9B,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,EAAE;yBACxD;qBACF;iBACF;gBACD,UAAU,EAAE,SAAS;aACtB,CAAC;SACH,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,CAAC,MAAM,MAAM,SAAS,EAAE,CAAC,CAAC;QACzE,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAG/B,CAAC;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,CAAC;QAExD,OAAO;YACL,OAAO;YACP,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;gBAClB,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,aAAa;gBACtC,gBAAgB,EAAE,IAAI,CAAC,KAAK,CAAC,iBAAiB;gBAC9C,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY;aACrC,CAAC,CAAC,CAAC,SAAS;SACd,CAAC;IACJ,CAAC;CACF"}

package/dist/tools/analyzeImage.d.ts

@@ -0,0 +1,31 @@
+import { VisionService } from '../services/visionService.js';
+export interface AnalyzeImageParams {
+    image_path: string;
+    prompt?: string;
+}
+export declare function createAnalyzeImageTool(visionService: VisionService): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            image_path: {
+                type: string;
+                description: string;
+            };
+            prompt: {
+                type: string;
+                description: string;
+                default: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (params: AnalyzeImageParams) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=analyzeImage.d.ts.map

package/dist/tools/analyzeImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzeImage.d.ts","sourceRoot":"","sources":["../../src/tools/analyzeImage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAG7D,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,aAAa;;;;;;;;;;;;;;;;;;sBAmBvC,kBAAkB;;;;;;EAiB7C"}

package/dist/tools/analyzeImage.js

@@ -0,0 +1,36 @@
+import { imagePathToData, imageDataToDataUrl } from '../utils/imageProcessor.js';
+export function createAnalyzeImageTool(visionService) {
+    return {
+        name: 'analyze_image',
+        description: 'Analyzes an image and returns a detailed description. Supports PNG, JPEG, GIF, WebP, and BMP formats.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                image_path: {
+                    type: 'string',
+                    description: 'Path to the image file to analyze',
+                },
+                prompt: {
+                    type: 'string',
+                    description: 'Custom prompt for image analysis',
+                    default: 'Describe this image in detail, including objects, text, colors, composition, and any notable features.',
+                },
+            },
+            required: ['image_path'],
+        },
+        handler: async (params) => {
+            const { image_path, prompt } = params;
+            const imageData = imagePathToData(image_path);
+            const imageDataUrl = imageDataToDataUrl(imageData);
+            const result = await visionService.analyze({
+                imageDataUrl,
+                prompt: prompt || 'Describe this image in detail, including objects, text, colors, composition, and any notable features.',
+                maxTokens: 4096,
+            });
+            return {
+                content: [{ type: 'text', text: result.content }],
+            };
+        },
+    };
+}
+//# sourceMappingURL=analyzeImage.js.map

package/dist/tools/analyzeImage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzeImage.js","sourceRoot":"","sources":["../../src/tools/analyzeImage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAOjF,MAAM,UAAU,sBAAsB,CAAC,aAA4B;IACjE,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,uGAAuG;QACpH,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mCAAmC;iBACjD;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,kCAAkC;oBAC/C,OAAO,EAAE,wGAAwG;iBAClH;aACF;YACD,QAAQ,EAAE,CAAC,YAAY,CAAC;SACzB;QACD,OAAO,EAAE,KAAK,EAAE,MAA0B,EAAE,EAAE;YAC5C,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;YAEtC,MAAM,SAAS,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;YAC9C,MAAM,YAAY,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;YAEnD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC;gBACzC,YAAY;gBACZ,MAAM,EAAE,MAAM,IAAI,wGAAwG;gBAC1H,SAAS,EAAE,IAAI;aAChB,CAAC,CAAC;YAEH,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;aAClD,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/utils/imageProcessor.d.ts

@@ -0,0 +1,10 @@
+export interface ImageData {
+    base64: string;
+    mimeType: string;
+    filename: string;
+}
+export declare function getMimeType(filePath: string): string;
+export declare function isValidImageFormat(filePath: string): boolean;
+export declare function imagePathToData(filePath: string): ImageData;
+export declare function imageDataToDataUrl(imageData: ImageData): string;
+//# sourceMappingURL=imageProcessor.d.ts.map

package/dist/utils/imageProcessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageProcessor.d.ts","sourceRoot":"","sources":["../../src/utils/imageProcessor.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAWD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAW3D;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAE/D"}

package/dist/utils/imageProcessor.js

@@ -0,0 +1,32 @@
+import { readFileSync } from 'fs';
+import { extname, basename } from 'path';
+const MIME_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.bmp': 'image/bmp',
+};
+export function getMimeType(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    return MIME_TYPES[ext] || 'application/octet-stream';
+}
+export function isValidImageFormat(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    return ext in MIME_TYPES;
+}
+export function imagePathToData(filePath) {
+    if (!isValidImageFormat(filePath)) {
+        throw new Error(`Unsupported image format: ${extname(filePath)}`);
+    }
+    const imageBuffer = readFileSync(filePath);
+    const base64 = imageBuffer.toString('base64');
+    const mimeType = getMimeType(filePath);
+    const filename = basename(filePath);
+    return { base64, mimeType, filename };
+}
+export function imageDataToDataUrl(imageData) {
+    return `data:${imageData.mimeType};base64,${imageData.base64}`;
+}
+//# sourceMappingURL=imageProcessor.js.map

package/dist/utils/imageProcessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageProcessor.js","sourceRoot":"","sources":["../../src/utils/imageProcessor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAQzC,MAAM,UAAU,GAA2B;IACzC,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;CACpB,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5C,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,0BAA0B,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5C,OAAO,GAAG,IAAI,UAAU,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,6BAA6B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,WAAW,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEpC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,SAAoB;IACrD,OAAO,QAAQ,SAAS,CAAC,QAAQ,WAAW,SAAS,CAAC,MAAM,EAAE,CAAC;AACjE,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@erickstryck/simple-vision-mcp",
+  "version": "1.0.0",
+  "description": "A lightweight MCP server for image analysis using OpenAI-compatible APIs",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "simple-vision-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc && node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": ["mcp", "vision", "image-analysis", "openai-compatible"],
+  "author": "erickstryck <erickstryck@hotmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/erickstryck/simple-vision-mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "dotenv": "^16.4.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/config/index.ts

@@ -0,0 +1,21 @@
+export interface ServerConfig {
+  apiKey: string;
+  baseUrl: string;
+  model: string;
+  maxTokens: number;
+  timeout: number;
+}
+
+export function loadConfig(): ServerConfig {
+  const apiKey = process.env.VISION_API_KEY || process.env.OPENAI_API_KEY || '';
+  const baseUrl = process.env.VISION_BASE_URL || process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1';
+  const model = process.env.VISION_MODEL || process.env.OPENAI_MODEL || 'gpt-4o-mini';
+  const maxTokens = parseInt(process.env.VISION_MAX_TOKENS || '4096', 10);
+  const timeout = parseInt(process.env.VISION_TIMEOUT || '120', 10);
+
+  if (!apiKey) {
+    throw new Error('VISION_API_KEY or OPENAI_API_KEY environment variable is required');
+  }
+
+  return { apiKey, baseUrl, model, maxTokens, timeout };
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { loadConfig } from './config/index.js';
+import { VisionService } from './services/visionService.js';
+import { createAnalyzeImageTool } from './tools/analyzeImage.js';
+
+class VisionMCPServer {
+  private server: Server;
+  private visionService: VisionService;
+
+  constructor() {
+    const config = loadConfig();
+    this.visionService = new VisionService(config);
+
+    this.server = new Server(
+      {
+        name: 'simple-vision-mcp',
+        version: '1.0.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.setupHandlers();
+  }
+
+  private setupHandlers(): void {
+    this.server.setRequestHandler(ListToolsRequestSchema, () => ({
+      tools: [createAnalyzeImageTool(this.visionService)],
+    }));
+
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+
+      if (name === 'analyze_image') {
+        const tool = createAnalyzeImageTool(this.visionService);
+        return await tool.handler(args as { image_path: string; prompt?: string });
+      }
+
+      throw new Error(`Unknown tool: ${name}`);
+    });
+  }
+
+  async run(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+  }
+}
+
+const server = new VisionMCPServer();
+server.run().catch((error) => {
+  console.error('Failed to start server:', error);
+  process.exit(1);
+});

package/src/services/visionService.ts

@@ -0,0 +1,66 @@
+import { ServerConfig } from '../config/index.js';
+
+export interface VisionRequest {
+  imageDataUrl: string;
+  prompt: string;
+  maxTokens: number;
+}
+
+export interface VisionResponse {
+  content: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+export class VisionService {
+  constructor(private readonly config: ServerConfig) {}
+
+  async analyze(request: VisionRequest): Promise<VisionResponse> {
+    const { imageDataUrl, prompt, maxTokens } = request;
+
+    const response = await fetch(`${this.config.baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.config.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.config.model,
+        messages: [
+          {
+            role: 'user',
+            content: [
+              { type: 'text', text: prompt },
+              { type: 'image_url', image_url: { url: imageDataUrl } },
+            ],
+          },
+        ],
+        max_tokens: maxTokens,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      throw new Error(`Vision API error: ${response.status} - ${errorBody}`);
+    }
+
+    const data = await response.json() as {
+      choices: Array<{ message: { content: string } }>;
+      usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
+    };
+
+    const content = data.choices[0]?.message?.content || '';
+
+    return {
+      content,
+      usage: data.usage ? {
+        promptTokens: data.usage.prompt_tokens,
+        completionTokens: data.usage.completion_tokens,
+        totalTokens: data.usage.total_tokens,
+      } : undefined,
+    };
+  }
+}

package/src/tools/analyzeImage.ts

@@ -0,0 +1,45 @@
+import { VisionService } from '../services/visionService.js';
+import { imagePathToData, imageDataToDataUrl } from '../utils/imageProcessor.js';
+
+export interface AnalyzeImageParams {
+  image_path: string;
+  prompt?: string;
+}
+
+export function createAnalyzeImageTool(visionService: VisionService) {
+  return {
+    name: 'analyze_image',
+    description: 'Analyzes an image and returns a detailed description. Supports PNG, JPEG, GIF, WebP, and BMP formats.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image_path: {
+          type: 'string',
+          description: 'Path to the image file to analyze',
+        },
+        prompt: {
+          type: 'string',
+          description: 'Custom prompt for image analysis',
+          default: 'Describe this image in detail, including objects, text, colors, composition, and any notable features.',
+        },
+      },
+      required: ['image_path'],
+    },
+    handler: async (params: AnalyzeImageParams) => {
+      const { image_path, prompt } = params;
+
+      const imageData = imagePathToData(image_path);
+      const imageDataUrl = imageDataToDataUrl(imageData);
+
+      const result = await visionService.analyze({
+        imageDataUrl,
+        prompt: prompt || 'Describe this image in detail, including objects, text, colors, composition, and any notable features.',
+        maxTokens: 4096,
+      });
+
+      return {
+        content: [{ type: 'text', text: result.content }],
+      };
+    },
+  };
+}

package/src/utils/imageProcessor.ts

@@ -0,0 +1,44 @@
+import { readFileSync } from 'fs';
+import { extname, basename } from 'path';
+
+export interface ImageData {
+  base64: string;
+  mimeType: string;
+  filename: string;
+}
+
+const MIME_TYPES: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.bmp': 'image/bmp',
+};
+
+export function getMimeType(filePath: string): string {
+  const ext = extname(filePath).toLowerCase();
+  return MIME_TYPES[ext] || 'application/octet-stream';
+}
+
+export function isValidImageFormat(filePath: string): boolean {
+  const ext = extname(filePath).toLowerCase();
+  return ext in MIME_TYPES;
+}
+
+export function imagePathToData(filePath: string): ImageData {
+  if (!isValidImageFormat(filePath)) {
+    throw new Error(`Unsupported image format: ${extname(filePath)}`);
+  }
+
+  const imageBuffer = readFileSync(filePath);
+  const base64 = imageBuffer.toString('base64');
+  const mimeType = getMimeType(filePath);
+  const filename = basename(filePath);
+
+  return { base64, mimeType, filename };
+}
+
+export function imageDataToDataUrl(imageData: ImageData): string {
+  return `data:${imageData.mimeType};base64,${imageData.base64}`;
+}

package/tests/config.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { loadConfig } from '../src/config/index.js';
+
+describe('Config', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    vi.resetModules();
+    process.env = { ...originalEnv };
+  });
+
+  it('should load config from environment variables', () => {
+    process.env.VISION_API_KEY = 'test-key';
+    process.env.VISION_BASE_URL = 'https://test.com/v1';
+    process.env.VISION_MODEL = 'test-model';
+
+    const config = loadConfig();
+
+    expect(config.apiKey).toBe('test-key');
+    expect(config.baseUrl).toBe('https://test.com/v1');
+    expect(config.model).toBe('test-model');
+  });
+
+  it('should use fallback values for optional settings', () => {
+    process.env.VISION_API_KEY = 'test-key';
+
+    const config = loadConfig();
+
+    expect(config.maxTokens).toBe(4096);
+    expect(config.timeout).toBe(120);
+  });
+
+  it('should throw error when API key is missing', () => {
+    delete process.env.VISION_API_KEY;
+    delete process.env.OPENAI_API_KEY;
+
+    expect(() => loadConfig()).toThrow('VISION_API_KEY or OPENAI_API_KEY environment variable is required');
+  });
+
+  it('should prefer VISION_* variables over OPENAI_* variables', () => {
+    process.env.VISION_API_KEY = 'vision-key';
+    process.env.OPENAI_API_KEY = 'openai-key';
+    process.env.VISION_BASE_URL = 'https://vision.com/v1';
+    process.env.OPENAI_BASE_URL = 'https://openai.com/v1';
+
+    const config = loadConfig();
+
+    expect(config.apiKey).toBe('vision-key');
+    expect(config.baseUrl).toBe('https://vision.com/v1');
+  });
+
+  it('should use OPENAI_* variables when VISION_* are not set', () => {
+    process.env.OPENAI_API_KEY = 'openai-key';
+    process.env.OPENAI_BASE_URL = 'https://openai.com/v1';
+    process.env.OPENAI_MODEL = 'gpt-4o';
+
+    const config = loadConfig();
+
+    expect(config.apiKey).toBe('openai-key');
+    expect(config.baseUrl).toBe('https://openai.com/v1');
+    expect(config.model).toBe('gpt-4o');
+  });
+});

package/tests/imageProcessor.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { writeFileSync, unlinkSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { imagePathToData, imageDataToDataUrl, getMimeType, isValidImageFormat } from '../src/utils/imageProcessor.js';
+
+describe('ImageProcessor', () => {
+  const testDir = '/tmp/simple-vision-mcp-tests';
+
+  beforeEach(() => {
+    if (!existsSync(testDir)) {
+      mkdirSync(testDir, { recursive: true });
+    }
+  });
+
+  describe('getMimeType', () => {
+    it('should return correct mime type for png', () => {
+      expect(getMimeType('/path/to/image.png')).toBe('image/png');
+    });
+
+    it('should return correct mime type for jpeg', () => {
+      expect(getMimeType('/path/to/image.jpg')).toBe('image/jpeg');
+      expect(getMimeType('/path/to/image.jpeg')).toBe('image/jpeg');
+    });
+
+    it('should return correct mime type for webp', () => {
+      expect(getMimeType('/path/to/image.webp')).toBe('image/webp');
+    });
+
+    it('should return correct mime type for gif', () => {
+      expect(getMimeType('/path/to/image.gif')).toBe('image/gif');
+    });
+
+    it('should return octet-stream for unknown formats', () => {
+      expect(getMimeType('/path/to/image.xyz')).toBe('application/octet-stream');
+    });
+  });
+
+  describe('isValidImageFormat', () => {
+    it('should return true for supported formats', () => {
+      expect(isValidImageFormat('image.png')).toBe(true);
+      expect(isValidImageFormat('image.jpg')).toBe(true);
+      expect(isValidImageFormat('image.jpeg')).toBe(true);
+      expect(isValidImageFormat('image.webp')).toBe(true);
+      expect(isValidImageFormat('image.gif')).toBe(true);
+      expect(isValidImageFormat('image.bmp')).toBe(true);
+    });
+
+    it('should return false for unsupported formats', () => {
+      expect(isValidImageFormat('image.pdf')).toBe(false);
+      expect(isValidImageFormat('image.txt')).toBe(false);
+      expect(isValidImageFormat('image.svg')).toBe(false);
+    });
+  });
+
+  describe('imagePathToData', () => {
+    it('should convert png file to base64 data', () => {
+      const testFile = join(testDir, 'test.png');
+      const pngData = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+      writeFileSync(testFile, pngData);
+
+      const result = imagePathToData(testFile);
+
+      expect(result.mimeType).toBe('image/png');
+      expect(result.base64).toBe(pngData.toString('base64'));
+      expect(result.filename).toBe('test.png');
+
+      unlinkSync(testFile);
+    });
+
+    it('should throw error for unsupported format', () => {
+      const testFile = join(testDir, 'test.pdf');
+      writeFileSync(testFile, Buffer.from('test'));
+
+      expect(() => imagePathToData(testFile)).toThrow('Unsupported image format: .pdf');
+
+      unlinkSync(testFile);
+    });
+
+    it('should throw error for non-existent file', () => {
+      expect(() => imagePathToData('/non/existent/file.png')).toThrow();
+    });
+  });
+
+  describe('imageDataToDataUrl', () => {
+    it('should convert image data to data URL', () => {
+      const imageData = {
+        base64: 'testbase64',
+        mimeType: 'image/png',
+        filename: 'test.png',
+      };
+
+      const result = imageDataToDataUrl(imageData);
+
+      expect(result).toBe('data:image/png;base64,testbase64');
+    });
+  });
+});

package/tests/visionService.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { VisionService } from '../src/services/visionService.js';
+import { ServerConfig } from '../src/config/index.js';
+
+describe('VisionService', () => {
+  const mockConfig: ServerConfig = {
+    apiKey: 'test-api-key',
+    baseUrl: 'https://api.test.com/v1',
+    model: 'test-model',
+    maxTokens: 4096,
+    timeout: 120,
+  };
+
+  let visionService: VisionService;
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch;
+    visionService = new VisionService(mockConfig);
+  });
+
+  it('should analyze image successfully', async () => {
+    const mockResponse = {
+      ok: true,
+      json: () => Promise.resolve({
+        choices: [{ message: { content: 'Test description' } }],
+        usage: { prompt_tokens: 100, completion_tokens: 50, total_tokens: 150 },
+      }),
+    };
+    mockFetch.mockResolvedValue(mockResponse);
+
+    const result = await visionService.analyze({
+      imageDataUrl: 'data:image/png;base64,test',
+      prompt: 'Describe this image',
+      maxTokens: 4096,
+    });
+
+    expect(result.content).toBe('Test description');
+    expect(result.usage?.totalTokens).toBe(150);
+  });
+
+  it('should throw error on API failure', async () => {
+    const mockResponse = {
+      ok: false,
+      status: 401,
+      text: () => Promise.resolve('Unauthorized'),
+    };
+    mockFetch.mockResolvedValue(mockResponse);
+
+    await expect(
+      visionService.analyze({
+        imageDataUrl: 'data:image/png;base64,test',
+        prompt: 'Describe this image',
+        maxTokens: 4096,
+      })
+    ).rejects.toThrow('Vision API error: 401 - Unauthorized');
+  });
+
+  it('should handle empty response', async () => {
+    const mockResponse = {
+      ok: true,
+      json: () => Promise.resolve({
+        choices: [{ message: { content: '' } }],
+      }),
+    };
+    mockFetch.mockResolvedValue(mockResponse);
+
+    const result = await visionService.analyze({
+      imageDataUrl: 'data:image/png;base64,test',
+      prompt: 'Describe this image',
+      maxTokens: 4096,
+    });
+
+    expect(result.content).toBe('');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+});