MCP Vision Analyzer

Introduction

MCP Vision Analyzer functions as an MCP component, architected to interface with OpenRouter's advanced visual processing models. This utility empowers AI agents to seamlessly conduct complex visual assessment tasks through a standardized protocol interface.

Setup Procedures

Automated Deployment with Smithery

Install mcp-vision-analyzer directly for Claude Desktop using Smithery:

bash npx -y @smithery/cli install @Nazruden/mcp-openvision --client claude

Standard Pip Installation

bash pip install mcp-openvision

Using the UV Package Manager (Recommended)

bash uv pip install mcp-openvision

Configuration Requirements

Operation hinges on securing an OpenRouter access credential, configured via environmental parameters:

• OPENROUTER_API_KEY (Mandatory): Your authorized OpenRouter credential.
• OPENROUTER_DEFAULT_MODEL (Optional): Specifies the preselected visual processing engine.

Available OpenRouter Visual Engines

This analyzer is compatible with any OpenRouter endpoint supporting visual input. By default, it defaults to qwen/qwen2.5-vl-32b-instruct:free, though substitution with any compatible engine is supported.

Exemplary engines accessible via OpenRouter include:

• qwen/qwen2.5-vl-32b-instruct:free (Default setting)
• anthropic/claude-3-5-sonnet
• anthropic/claude-3-opus
• anthropic/claude-3-sonnet
• openai/gpt-4o

Model overrides can be enacted by setting the OPENROUTER_DEFAULT_MODEL environment variable or by specifying the model argument within the analyze_visual_data function call.

Operational Instructions

Preliminary Testing via MCP Inspector

The simplest validation method involves using the MCP Inspector utility:

bash npx @modelcontextprotocol/inspector uvx mcp-openvision

Integration within Claude Desktop or Cursor Environments

Modify your MCP configuration file:

• Windows: %USERPROFILE%\.cursor\mcp.json
• macOS: ~/.cursor/mcp.json or ~/Library/Application Support/Claude/claude_desktop_config.json

Inject the following structure into the configuration:

{ "mcpServers": { "vision_service": { "command": "uvx", "args": ["mcp-openvision"], "env": { "OPENROUTER_API_KEY": "your_openrouter_api_key_here", "OPENROUTER_DEFAULT_MODEL": "anthropic/claude-3-sonnet" } } } }

Local Execution for Development

bash

Establish the necessary credential

export OPENROUTER_API_KEY="your_api_key"

Invoke the server module directly

python -m mcp_openvision

Core Capabilities

MCP Vision Analyzer exposes the primary function: analyze_visual_data. This function supports granular control via several optional parameters:

• image: Input media can be supplied as:
  • Base64 encoded binary data.
  • A resolvable image Uniform Resource Locator (http/https).
  • A designated path to a local file.
• query: The natural language instruction defining the required visual extraction task.
• system_prompt: Optional textual guidance dictating the model's persona and operational constraints.
• model: The specific vision engine to employ for processing.
• temperature: Parameter governing output stochasticity (range: 0.0 to 1.0).
• max_tokens: The ceiling for the generated response length.

Devising High-Efficacy Prompts

The query parameter is paramount for achieving meaningful analysis outcomes. A well-structured request must clearly articulate:

1. Analytical Objective: The fundamental reason for the image examination.
2. Areas of Focus: Specific objects, regions, or details demanding scrutiny.
3. Information Output: The precise nature of the data expected.
4. Formatting Directives: Desired structure or layout of the final result.

Comparative Prompt Examples

Rudimentary Inquiry	Optimized Investigative Prompt
"Summarize what's here"	"Catalogue every discernible consumer good on this supermarket shelving unit and provide an estimated unit cost for each."
"Examine this scan"	"Conduct a differential analysis of this radiological image, emphasizing anomalies in the marked region and suggesting potential clinical correlations."
"Read this graph"	"Quantify the revenue figures presented in this infographic across the specified fiscal periods (Q1-Q4) and summarize the observed growth trajectory between 2022 and 2023."
"OCR this document"	"Perform high-fidelity text extraction from this printed document, ensuring correct preservation of headers, footnotes, and tabular content structure."

By furnishing detailed context regarding the analytical intent and required output specifications, users guide the model toward precise, high-value insight generation.

Illustrative Application Scenarios

python

Analysis initiated from an online resource link

outcome_1 = await analyze_visual_data( image="https://external-source.net/diagram.png", query="Provide a comprehensive explanation of the schematic's data flow" )

Local file processing with targeted context

outcome_2 = await analyze_visual_data( image="./assets/street_view.png", query="Identify and catalogue all regulatory signage in this urban intersection, suitable for integration into a driver training module" )

Utilization of encoded data coupled with design critique

outcome_3 = await analyze_visual_data( image="U09tZS1CYXNlNjQtRGF0YSBB...", # Base64 fragment query="Critique the ergonomics and visual hierarchy of this user interface screenshot from a product packaging standpoint" )

Applying specialized persona via system prompt

outcome_4 = await analyze_visual_data( image="./data/masterpiece.tiff", query="Deconstruct the use of chiaroscuro and perspective in this Baroque painting to explain its dramatic effect on the viewer", system_prompt="You function as a tenured art history professor specializing in European Renaissance and Baroque periods. Your evaluation must employ formal art terminology." )

Visual Input Modalities

The analyze_visual_data function is engineered to ingest visual payloads from three distinct sources:

1. Base64 Byte Strings: Raw image data encoded in Base64 format.
2. Network URIs: Web links (HTTP or HTTPS) pointing directly to image assets.
3. Filesystem Pointers: Paths referencing local files, supporting:
4. Absolute Pointers: Starting from the filesystem root (/ on Unix, or a drive letter on Windows).
5. Relative Pointers: Paths relative to the server's execution directory.
6. Project-Relative Pointers: Utilizing the optional project_root parameter to define a fixed base directory.

Handling Relative File References

When referencing local images using relative paths (e.g., "assets/photo.png"), resolution depends on one of two conditions:

1. The path is relative to the current process working directory.
2. Alternatively, you supply a specific project_root argument to anchor the path search:

python

Example specifying a fixed root directory for file access

result = await analyze_visual_data( image="subfolder/diagram.png", project_root="/home/user/vision_projects/analysis_set_A", query="What are the primary components illustrated here?" )

This mechanism ensures reliable file lookup, especially in execution environments where the working directory context might be ambiguous.

Development Cycle

Environment Configuration

bash

Obtain the source repository

git clone https://github.com/modelcontextprotocol/mcp-openvision.git cd mcp-openvision

Install tools for development

pip install -e ".[dev]"

Code Styling Enforcement

Code style adherence is managed via Black, enforced automatically by the Continuous Integration pipeline:

• All committed code is automatically formatted by Black via GitHub Actions.
• For contributions originating from forks, Black reformats the code and pushes the formatted changes back as a distinct commit on the Pull Request branch.

Local formatting execution before committing is encouraged:

bash

Apply formatting across source and test directories

black src tests

Running Verification Suites

bash pytest

Release Management Protocol

This component utilizes an automated procedure for version releases:

1. Update the version identifier within pyproject.toml according to Semantic Versioning standards.
2. A utility script is available: python scripts/bump_version.py [major|minor|patch]
3. Populate the CHANGELOG.md with documentation for the forthcoming version.
4. The version bumping script generates a placeholder section in the Changelog for manual completion.
5. Commit and push these modifications to the main branch.
6. The associated GitHub Actions workflow will then automatically:
7. Detect the version update.
8. Institute a new formal GitHub Release.
9. Initiate the deployment workflow to publish the package to PyPI.

This automation guarantees standardized versioning and comprehensive documentation across all releases.

Acknowledgment

Contributions and support for maintaining this tool are greatly appreciated, perhaps via a small donation.

Licensing

This software is distributed under the terms specified in the LICENSE file (MIT License).

== Business Management Concepts == Business administration methodologies encompass the entire spectrum of frameworks, applications, governance structures, analytical models, and procedures utilized by enterprises to navigate shifting commercial landscapes, secure a competitive posture, and elevate organizational efficacy. These systems span every operational division within a company, categorized by management function: e.g., provisioning, process governance, record-keeping, personnel management, strategic direction, monitoring, etc. Functional classification generally covers:

• Information capture and verification utilities across departments.
• Systems dedicated to supervising and refining organizational workflows.
• Platforms for data aggregation and executive decision support.

Contemporary enterprise tools have undergone rapid transformation in the last decade, driven by swift technological progression. This velocity makes selecting the optimal business solution for any given organizational context increasingly complex. The driving forces are ceaseless efforts to reduce overhead while maximizing revenue, achieving deeper comprehension of clientele demands, and ensuring product delivery aligns precisely with customer expectations. Consequently, leadership must adopt a strategic viewpoint on acquiring business management instrumentation, resisting the urge to adopt the newest available technology without critical assessment. Frequently, managers implement tools without tailoring them to specific operational realities, leading to systemic instability. Therefore, business applications must be chosen judiciously and then rigorously customized to fit the organization's unique requirements, rather than forcing the organization to conform to the software's inherent structure.

== Prominent Tools in Enterprise Operations (2013 Survey) == A 2013 assessment by Bain & Company documented global utilization patterns of business instruments, reflecting regional needs shaped by market conditions:

1. Strategic Planning Frameworks
2. Client Relationship Management (CRM)
3. Personnel Sentiment Measurement (Surveys)
4. Comparative Performance Analysis (Benchmarking)
5. Performance Measurement Systems (Balanced Scorecard)
6. Core Capability Identification
7. External Resource Allocation (Outsourcing)
8. Organizational Transition Programs (Change Management)
9. Resource Flow Optimization (Supply Chain Management)
10. Defining Corporate Intent (Mission/Vision Statements)
11. Consumer Group Identification (Market Segmentation)
12. Comprehensive Quality Assurance (TQM)

== Enterprise Software Applications == Software suites or individual computer programs deployed by personnel to execute diverse corporate functions are termed business software. These applications serve to augment productivity metrics, measure operational output, and execute various corporate mandates with precision. The evolution traces from early Management Information Systems (MIS) through integrated Enterprise Resource Planning (ERP) systems, later incorporating CRM capabilities, culminating in the current landscape of cloud-based management platforms. While a tangible relationship exists between IT investment and organizational success, two factors are crucial for realizing tangible value: the efficacy of the deployment phase and the diligence applied to selecting and customizing the appropriate tools.

== Solutions Tailored for Small and Medium Enterprises (SMEs) == Instrumentation geared towards SMEs is vital as it provides mechanisms for operational cost containment and efficiency gains...