{"_id":"@akirose/image-recognition-mcp","name":"@akirose/image-recognition-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@akirose/image-recognition-mcp","version":"1.0.0","mcpName":"io.github.shalevshalit/image-recognition-mcp","description":"MCP server for AI-powered image recognition and description using OpenAI-compatible vision models.","type":"module","main":"dist/index.js","bin":{"image-recognition-mcp":"dist/index.js"},"repository":{"type":"git","url":"git+https://github.com/akirose/image-recognition-mcp.git"},"publishConfig":{"access":"public"},"author":{"name":"akirose"},"license":"MIT","engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.15.0","openai":"^5.8.3"},"devDependencies":{"@types/node":"^24.0.12","shx":"^0.4.0","typescript":"^5.0.0","vitest":"^1.6.0"},"scripts":{"test":"vitest run","test:unit":"vitest run test/index.test.ts","test:integration":"OPENAI_BASE_URL=http://127.0.0.1:1234/v1 OPENAI_MODEL=qwen/qwen3-vl-4b ALLOWED_IMAGE_PATHS=./test vitest run test/describe-image-integration.test.ts","start":"node index.js","build":"tsc && shx chmod +x dist/*.js","prepare":"npm run build","prepublishOnly":"npm run build"},"_id":"@akirose/image-recognition-mcp@1.0.0","gitHead":"9707e720c343f82ec2f7c26ad3b0c26e03fa3f4a","bugs":{"url":"https://github.com/akirose/image-recognition-mcp/issues"},"homepage":"https://github.com/akirose/image-recognition-mcp#readme","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-6uOJtggu/fbOitn6+hvJA/qb7SvOoHBiob5m9ibAkIR8w77Hb8WPmIlv8wcKFz5+wSd81lBEmNaXfcmdR5lmUA==","shasum":"4330b1a89f226ca105b732994ec113febc4dc33b","tarball":"https://registry.npmjs.org/@akirose/image-recognition-mcp/-/image-recognition-mcp-1.0.0.tgz","fileCount":6,"unpackedSize":16916,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGn1UIc9jWHeRKux1qDORCuppjY50jTuI59kyDAKGaRFAiEA0xJ0Hn/qrs9pwsUK9TnkYRvm5BRHxFONTnYyy+Z6W0U="}]},"_npmUser":{"name":"akirose","email":"cmk1024@naver.com"},"directories":{},"maintainers":[{"name":"akirose","email":"cmk1024@naver.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/image-recognition-mcp_1.0.0_1763300859679_0.6235294926360451"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-16T13:47:39.575Z","1.0.0":"2025-11-16T13:47:39.881Z","modified":"2025-11-16T13:47:40.483Z"},"maintainers":[{"name":"akirose","email":"cmk1024@naver.com"}],"description":"MCP server for AI-powered image recognition and description using OpenAI-compatible vision models.","homepage":"https://github.com/akirose/image-recognition-mcp#readme","repository":{"type":"git","url":"git+https://github.com/akirose/image-recognition-mcp.git"},"author":{"name":"akirose"},"bugs":{"url":"https://github.com/akirose/image-recognition-mcp/issues"},"license":"MIT","readme":"# Image Recognition MCP Server\n\nA Model Context Protocol (MCP) server that provides AI-powered image recognition and description capabilities using OpenAI-compatible vision models.\n\n## Overview\n\nThis MCP server enables AI assistants to analyze and describe images through a simple URL-based interface. It supports OpenAI's vision models as well as OpenAI-compatible local models (such as LM Studio, Ollama, etc.), providing detailed descriptions of images and making it easy to integrate image analysis capabilities into your AI workflows.\n\n## Features\n\n- **Image Analysis**: Analyze images from URLs and get detailed descriptions\n- **Flexible Model Support**: Works with OpenAI's vision models and OpenAI-compatible local models (LM Studio, Ollama, etc.)\n- **MCP Protocol**: Fully compatible with the Model Context Protocol standard\n- **TypeScript**: Built with TypeScript for type safety and better development experience\n- **Simple API**: Easy-to-use interface for image description requests\n\n## Installation\n\n### Prerequisites\n\n- Node.js 18+\n- npm or yarn\n- OpenAI API key or local vision model server (e.g., LM Studio, Ollama)\n\n### MCP Client Configuration\n\nTo use this server with an MCP client, add the following configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"image-recognition\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@akirose/image-recognition-mcp\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"your-actual-openai-api-key-here\"\n      }\n    }\n  }\n}\n```\n\nTo allow access to image files from any path, set `ALLOW_ALL_PATHS` to `true`:\n\n```json\n{\n  \"mcpServers\": {\n    \"image-recognition\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@akirose/image-recognition-mcp\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"your-actual-openai-api-key-here\",\n        \"ALLOW_ALL_PATHS\": \"true\"\n      }\n    }\n  }\n}\n```\n\n**⚠️ IMPORTANT:** The `env` section with your API key is required - this is the only way the MCP server can function. For local models, you can use any placeholder value for `OPENAI_API_KEY` and configure `OPENAI_BASE_URL` to point to your local server.\n\n### Environment Variables\n\nThe server supports the following environment variables:\n\n- `OPENAI_API_KEY` - Your OpenAI API key, or any placeholder value when using local models (required)\n- `OPENAI_BASE_URL` - Base URL for OpenAI API or OpenAI-compatible API servers (optional, defaults to OpenAI's official API)\n  - Example for LM Studio: `\"http://127.0.0.1:1234/v1\"`\n  - Example for Ollama: `\"http://localhost:11434/v1\"`\n- `OPENAI_MODEL` - The vision model to use for image recognition (optional, defaults to \"gpt-5-mini\")\n  - For OpenAI: `\"gpt-5-mini\"`, `\"gpt-4o\"`, `\"gpt-4o-mini\"`, etc.\n  - For local models: `\"llava\"`, `\"qwen/qwen3-vl-4b\"`, or any locally available vision model\n- `ALLOWED_IMAGE_PATHS` - Comma-separated list of allowed local file paths (optional, defaults to \"./images,./assets\")\n  - Example: `\"./images,./assets,./downloads\"`\n- `ALLOW_ALL_PATHS` - Set to \"true\" to allow access to image files from any path. When enabled, only image file extensions (.jpg, .jpeg, .png, .gif, .webp) are allowed for security (optional, defaults to false)\n- `ALLOWED_DOMAINS` - Comma-separated list of allowed URL domains for enhanced security (optional, defaults to allow all domains)\n  - Example: `\"example.com,cdn.example.com,images.example.org\"`\n  - When not set: All domains are allowed\n  - When set: Only specified domains will be allowed for URL-based image requests\n\n## Usage\n\n### Available Tools\n\n#### `describe-image`\n\nAnalyzes an image from a URL or local file path and provides a detailed description.\n\n**Parameters:**\n\n- `imageUrl` (string): The URL of the image to analyze, or a local file path\n- `prompt` (string, optional): The question or prompt to ask about the image (defaults to \"what's in this image?\")\n\n**Example with URL:**\n\n```json\n{\n  \"tool\": \"describe-image\",\n  \"arguments\": {\n    \"imageUrl\": \"https://example.com/image.jpg\",\n    \"prompt\": \"what's in this image?\"\n  }\n}\n```\n\n**Example with local file:**\n\n```json\n{\n  \"tool\": \"describe-image\",\n  \"arguments\": {\n    \"imageUrl\": \"./images/my-image.png\",\n    \"prompt\": \"Describe the objects in this image\"\n  }\n}\n```\n\n**Response:**\n\n```json\n{\n  \"content\": [\n    {\n      \"type\": \"text\",\n      \"text\": \"The image shows a beautiful sunset over a mountain landscape with vibrant orange and pink colors in the sky...\"\n    }\n  ]\n}\n```\n\n### Integration with AI Assistants\n\nThis MCP server can be integrated with various AI assistants that support the MCP protocol, such as:\n\n- Claude Desktop\n- Other MCP-compatible AI systems\n\n## Development\n\n### Project Structure\n\n```\nimage-recognition-mcp/\n├── src/\n│   ├── index.ts                # Main server implementation\n│   ├── path-validator.ts       # Path validation and security functions\n│   └── image-processor.ts      # Image processing utilities\n├── test/\n│   ├── index.test.ts           # Unit tests\n│   ├── describe-image-integration.test.ts  # Integration tests\n│   ├── test.png                # Test image\n│   └── README.md               # Test documentation\n├── dist/                       # Compiled JavaScript output\n├── package.json                # Project dependencies and scripts\n├── tsconfig.json               # TypeScript configuration\n└── README.md                   # This file\n```\n\n### Running Tests\n\nThe project includes both unit tests and integration tests:\n\n```bash\n# Run all tests\nnpm test\n\n# Run unit tests only\nnpm run test:unit\n\n# Run integration tests with local OpenAI-compatible server\nnpm run test:integration\n```\n\n**Integration Tests Requirements:**\n- A running OpenAI-compatible API server at `http://127.0.0.1:1234/v1`\n- The server should support vision models (e.g., qwen/qwen3-vl-4b)\n- You can use LM Studio, Ollama, or other compatible servers\n- The integration tests use the `OPENAI_BASE_URL` and `OPENAI_MODEL` environment variables\n\nThe integration tests will:\n- Test actual API calls to the vision model\n- Verify image processing with the test image (`test/test.png`)\n- Validate the complete MCP tool workflow with both default and custom prompts\n- Test error handling and edge cases\n\n### Security Features\n\nThe server includes several security features:\n\n- **Path Validation**: Restricts local file access to allowed directories\n- **Extension Validation**: Only allows specific image file extensions (.jpg, .jpeg, .png, .gif, .webp)\n- **Domain Restriction**: Optional URL domain whitelist for enhanced security\n- **File Existence Checks**: Validates files exist before processing\n\n### Error Handling\n\nThe server includes robust error handling for:\n\n- Invalid image URLs\n- Unauthorized file paths or domains\n- Network connectivity issues\n- OpenAI API errors\n- Invalid input parameters\n- Unsupported file formats\n\n## Troubleshooting\n\n### Common Issues\n\n**Server fails to start or doesn't work:**\n\n- ✅ **Check if OpenAI API key is set**: This is the #1 cause of issues\n  ```bash\n  echo $OPENAI_API_KEY  # Should show your API key\n  ```\n- ✅ **Verify API key is valid**: Test with OpenAI's API directly\n- ✅ **Check API key has sufficient credits**: Ensure your OpenAI account has available credits\n\n**\"Authentication failed\" errors:**\n\n- The OpenAI API key is missing or invalid\n- Set the environment variable: `export OPENAI_API_KEY=\"your-key\"`\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for details.\n\n## Support\n\nFor support, please open an issue in the GitHub repository or contact the maintainer.\n","readmeFilename":"README.md","_rev":"1-11ea5fb9f0d349f2643b747843b24c0e"}