feat: add Mistral AI provider with dedicated OCR support (#106)

## Summary
- Add Mistral AI provider with 10 tools and 17 models
- Tools: ask, analyze_image, process_ocr, transcribe_audio, get_embeddings, moderate_content, fill_in_middle, list_models, server_info, test_connection
- Models: Frontier (Large/Medium/Small), Reasoning (Magistral), Vision (Pixtral), Audio (Voxtral), Coding (Codestral/Devstral), Embeddings, OCR, Moderation
- Supports reasoning model thinking output with optional `include_thinking` parameter
- GPT-5 reviewed and approved implementation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: cmpriestley

.mcp.json

@@ -5,6 +5,12 @@
       "command": "mcp-google-calendar",
       "args": [],
       "env": {}
+    },
+    "mistral": {
+      "type": "stdio",
+      "command": "mcp-mistral",
+      "args": [],
+      "env": {}
     }
   }
 }

PKGBUILD

@@ -1,7 +1,7 @@
 # Maintainer: Will Handley <[email protected]>
 _pkgname=mcp-handley-lab
 pkgname=python-mcp-handley-lab
-pkgver=0.13.3
+pkgver=0.14.0
 pkgrel=1
 pkgdesc="MCP Handley Lab - A comprehensive MCP toolkit for research productivity and lab management"
 arch=('any')
@@ -37,18 +37,16 @@ depends=(
     'python-pendulum'
     'python-xai-sdk'
     'jupyter-nbformat>=5.0.0'
-    'python-nbclient>=0.8.0'
+    'jupyter-nbclient>=0.8.0'
     'python-dateparser'
     'python-ftfy'
     'python-inscriptis'
     'python-selectolax'
     'python-email-reply-parser'
     'python-anthropic'
+    'python-mistralai>=1.9.0'
     'python-wolframclient'
     'python-opentelemetry-sdk'
-    'python-chromadb>=1.0.0'
-    'python-mail-parser>=3.15.0'
-    'python-pyfzf>=0.3.1'
     'python-dateutil>=2.8.0'
 )
 makedepends=(
@@ -71,6 +69,7 @@ optdepends=(
     'python-code2prompt: Codebase analysis'
     'python-black: Code formatting'
     'python-ruff: Linting'
+    'python-chromadb: Semantic search features (AUR)'
 )
 source=()
 sha256sums=()

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mcp-handley-lab"
-version = "0.13.3"
+version = "0.14.0"
 description = "MCP Handley Lab - A comprehensive MCP toolkit for research productivity and lab management"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -22,6 +22,7 @@ dependencies = [
     "googlemaps>=4.0.0",
     "openai>=1.0.0",
     "anthropic>=0.21.3",
+    "mistralai>=1.9.0",
     "xai-sdk>=1.0.0",
     "Pillow>=10.0.0",
     "httpx>=0.25.0",
@@ -32,15 +33,12 @@ dependencies = [
     "jmespath>=1.0.0",
     "watchdog>=3.0.0",
     "msal>=1.20.0",
-    "chromadb>=1.0.0",
     "nbformat>=5.0.0",
     "nbclient>=0.8.0",
-    "pyfzf>=0.3.1",
     "click>=8.0.0",
     "html2text>=2020.1.16",
     "beautifulsoup4>=4.12.0",
     "markdownify>=0.11.0",
-    "mail-parser>=3.15.0",
     "email-reply-parser>=0.5.0",
     "selectolax>=0.3.0",
     "inscriptis>=2.5.0",
@@ -79,6 +77,7 @@ mcp-gemini = "mcp_handley_lab.llm.gemini.tool:mcp.run"
 mcp-openai = "mcp_handley_lab.llm.openai.tool:mcp.run"
 mcp-claude = "mcp_handley_lab.llm.claude.tool:mcp.run"
 mcp-grok = "mcp_handley_lab.llm.grok.tool:mcp.run"
+mcp-mistral = "mcp_handley_lab.llm.mistral.tool:mcp.run"
 mcp-google-maps = "mcp_handley_lab.google_maps.tool:mcp.run"
 mcp-email = "mcp_handley_lab.email.tool:mcp.run"
 mcp-mutt-aliases = "mcp_handley_lab.email.mutt_aliases.tool:mcp.run"

src/mcp_handley_lab/code2prompt/tool.py

@@ -74,16 +74,13 @@ def generate_prompt(
         "cl100k",
         description="The name of the tiktoken encoding to use for token counting (e.g., 'cl100k', 'p50k_base').",
     ),
-    tokens: str = Field(
+    token_format: str = Field(
         "format",
-        description="Determines how token counts are displayed. Valid options are 'format', 'only', 'none'.",
+        description="Determines how token counts are displayed. Valid options are 'format' (human readable) or 'raw' (machine parsable).",
     ),
     sort: str = Field(
         "name_asc",
-        description="The sorting order for files. Options: 'name_asc', 'name_desc', 'tokens_asc', 'tokens_desc'.",
-    ),
-    include_priority: bool = Field(
-        False, description="'include' patterns take priority over .gitignore rules."
+        description="The sorting order for files. Options: 'name_asc', 'name_desc', 'date_asc', 'date_desc'.",
     ),
     template: str = Field(
         "", description="Path to a custom Jinja2 template file to format the output."
@@ -116,10 +113,9 @@ def generate_prompt(
         {"name": "--output-file", "value": output_file, "type": "value"},
         {"name": "--output-format", "value": output_format, "type": "value"},
         {"name": "--encoding", "value": encoding, "type": "value"},
-        {"name": "--tokens", "value": tokens, "type": "value"},
+        {"name": "--token-format", "value": token_format, "type": "value"},
         {"name": "--sort", "value": sort, "type": "value"},
         {"name": "--template", "value": template, "type": "optional_value"},
-        {"name": "--include-priority", "condition": include_priority, "type": "flag"},
         {"name": "--no-ignore", "condition": no_ignore, "type": "flag"},
         {"name": "--line-numbers", "condition": line_numbers, "type": "flag"},
         {

src/mcp_handley_lab/common/config.py

@@ -25,6 +25,9 @@ class Settings(BaseSettings):
     xai_api_key: str = Field(
         default="YOUR_API_KEY_HERE", description="API key for xAI Grok services."
     )
+    mistral_api_key: str = Field(
+        default="YOUR_API_KEY_HERE", description="API key for Mistral AI services."
+    )
     google_maps_api_key: str = Field(
         default="YOUR_API_KEY_HERE", description="API key for Google Maps services."
     )

src/mcp_handley_lab/llm/mistral/__init__.py

@@ -0,0 +1 @@
+"""Mistral LLM tool for AI interactions via MCP."""

src/mcp_handley_lab/llm/mistral/models.yaml

@@ -0,0 +1,248 @@
+models:
+  # === FRONTIER GENERALIST MODELS ===
+  mistral-large-latest:
+    description: "Latest flagship model - Mistral Large 3 (v25.12)"
+    capabilities: "🎯 Best for: Complex reasoning, analysis, multimodal tasks"
+    tags: ["mistral-large", "latest", "frontier", "multimodal"]
+    context_window: "128,000 tokens"
+    output_tokens: 8192
+    supports_vision: true
+    supports_grounding: false
+    input_per_1m: 2.00
+    output_per_1m: 6.00
+
+  mistral-medium-latest:
+    description: "Mistral Medium 3.1 - frontier multimodal model (v25.08)"
+    capabilities: "🎯 Best for: Complex tasks, balanced cost/performance"
+    tags: ["mistral-medium", "latest", "frontier", "multimodal"]
+    context_window: "128,000 tokens"
+    output_tokens: 8192
+    supports_vision: true
+    supports_grounding: false
+    input_per_1m: 0.40
+    output_per_1m: 2.00
+
+  mistral-small-latest:
+    description: "Mistral Small 3.2 - efficient general model (v25.06)"
+    capabilities: "⚡ Best for: Everyday tasks, cost-effective"
+    tags: ["mistral-small", "latest", "cost-effective"]
+    context_window: "128,000 tokens"
+    output_tokens: 8192
+    supports_vision: true
+    supports_grounding: false
+    input_per_1m: 0.10
+    output_per_1m: 0.30
+
+  # === MINISTRAL EDGE MODELS ===
+  ministral-3b-latest:
+    description: "Ministral 3 3B - tiny efficient model with vision (v25.12)"
+    capabilities: "🚀 Best for: Edge deployment, ultra-low latency"
+    tags: ["ministral", "edge", "cost-effective", "vision"]
+    context_window: "128,000 tokens"
+    output_tokens: 8192
+    supports_vision: true
+    supports_grounding: false
+    input_per_1m: 0.04
+    output_per_1m: 0.04
+
+  ministral-8b-latest:
+    description: "Ministral 3 8B - efficient model with vision (v25.12)"
+    capabilities: "🚀 Best for: Fast inference, high-volume tasks"
+    tags: ["ministral", "edge", "cost-effective", "vision"]
+    context_window: "128,000 tokens"
+    output_tokens: 8192
+    supports_vision: true
+    supports_grounding: false
+    input_per_1m: 0.10
+    output_per_1m: 0.10
+
+  # === REASONING MODELS (MAGISTRAL) ===
+  magistral-medium-latest:
+    description: "Magistral Medium 1.2 - frontier reasoning model (v25.09)"
+    capabilities: "🧠 Best for: Complex reasoning, step-by-step thinking"
+    tags: ["magistral", "reasoning", "frontier"]
+    context_window: "40,000 tokens"
+    output_tokens: 40000
+    supports_vision: false
+    supports_grounding: false
+    supports_reasoning: true
+    input_per_1m: 2.00
+    output_per_1m: 5.00
+
+  magistral-small-latest:
+    description: "Magistral Small 1.2 - efficient reasoning model (v25.09)"
+    capabilities: "🧠 Best for: Cost-effective reasoning tasks"
+    tags: ["magistral", "reasoning", "cost-effective"]
+    context_window: "40,000 tokens"
+    output_tokens: 40000
+    supports_vision: false
+    supports_grounding: false
+    supports_reasoning: true
+    input_per_1m: 0.50
+    output_per_1m: 1.50
+
+  # === CODING MODELS ===
+  codestral-latest:
+    description: "Codestral - cutting-edge coding model (v25.08)"
+    capabilities: "💻 Best for: Code generation, completion, debugging"
+    tags: ["codestral", "coding", "latest"]
+    context_window: "256,000 tokens"
+    output_tokens: 8192
+    supports_vision: false
+    supports_grounding: false
+    supports_fim: true
+    input_per_1m: 0.30
+    output_per_1m: 0.90
+
+  devstral-small-latest:
+    description: "Devstral Small 1.1 - open SWE model (v25.07)"
+    capabilities: "💻 Best for: Software engineering tasks"
+    tags: ["devstral", "coding", "swe"]
+    context_window: "128,000 tokens"
+    output_tokens: 8192
+    supports_vision: false
+    supports_grounding: false
+    supports_fim: true
+    input_per_1m: 0.10
+    output_per_1m: 0.30
+
+  # === VISION MODELS (PIXTRAL) ===
+  pixtral-large-latest:
+    description: "Pixtral Large - multimodal vision model (v24.11)"
+    capabilities: "👁️ Best for: Image analysis, multimodal tasks"
+    tags: ["pixtral", "vision", "multimodal"]
+    context_window: "128,000 tokens"
+    output_tokens: 8192
+    supports_vision: true
+    supports_grounding: false
+    input_per_1m: 2.00
+    output_per_1m: 6.00
+
+  pixtral-12b-2409:
+    description: "Pixtral 12B - lightweight vision model"
+    capabilities: "👁️ Best for: OCR, cost-effective vision tasks"
+    tags: ["pixtral", "vision", "cost-effective"]
+    context_window: "128,000 tokens"
+    output_tokens: 8192
+    supports_vision: true
+    supports_grounding: false
+    input_per_1m: 0.15
+    output_per_1m: 0.15
+
+  # === AUDIO MODELS (VOXTRAL) ===
+  voxtral-small-latest:
+    description: "Voxtral Small - audio chat model (v25.07)"
+    capabilities: "🎤 Best for: Audio conversations, voice understanding"
+    tags: ["voxtral", "audio", "chat"]
+    context_window: "128,000 tokens"
+    output_tokens: 8192
+    supports_vision: false
+    supports_grounding: false
+    supports_audio: true
+    input_per_1m: 0.20
+    output_per_1m: 0.60
+
+  voxtral-mini-latest:
+    description: "Voxtral Mini - audio transcription model (v25.07)"
+    capabilities: "🎤 Best for: Speech-to-text, transcription"
+    tags: ["voxtral", "audio", "transcription"]
+    context_window: "128,000 tokens"
+    output_tokens: 8192
+    supports_vision: false
+    supports_grounding: false
+    supports_audio: true
+    supports_transcription: true
+    input_per_1m: 0.10
+    output_per_1m: 0.30
+
+  # === SPECIALIST MODELS ===
+  mistral-ocr-latest:
+    description: "Dedicated OCR model for document text extraction"
+    capabilities: "📄 Best for: OCR, document parsing, PDF extraction"
+    tags: ["ocr", "document-ai"]
+    context_window: "N/A (document processing)"
+    output_tokens: 0
+    supports_vision: true
+    supports_grounding: false
+    # Pricing: $1 per 1,000 pages
+    input_per_1m: 1.00
+    output_per_1m: 0.00
+
+  mistral-moderation-latest:
+    description: "Content moderation model (v24.11)"
+    capabilities: "🛡️ Best for: Content safety, harmful text detection"
+    tags: ["moderation", "safety"]
+    context_window: "8,000 tokens"
+    output_tokens: 0
+    supports_vision: false
+    supports_grounding: false
+    input_per_1m: 0.10
+    output_per_1m: 0.00
+
+  # === EMBEDDING MODELS ===
+  mistral-embed:
+    description: "Text embedding model for semantic search"
+    capabilities: "🔍 Best for: RAG, semantic search, clustering"
+    tags: ["embedding", "text"]
+    context_window: "8,000 tokens"
+    output_tokens: 0
+    supports_vision: false
+    supports_grounding: false
+    embedding_dimensions: 1024
+    input_per_1m: 0.10
+    output_per_1m: 0.00
+
+  codestral-embed:
+    description: "Code embedding model (v25.05)"
+    capabilities: "🔍 Best for: Code search, repository exploration"
+    tags: ["embedding", "code"]
+    context_window: "32,000 tokens"
+    output_tokens: 0
+    supports_vision: false
+    supports_grounding: false
+    embedding_dimensions: 1024
+    input_per_1m: 0.20
+    output_per_1m: 0.00
+
+# Display categories (how to group models by tags for presentation)
+display_categories:
+  - name: "🎯 Frontier Generalist"
+    tags: ["frontier"]
+    description: "Most capable models for complex tasks"
+  - name: "🧠 Reasoning Models"
+    tags: ["magistral", "reasoning"]
+    description: "Step-by-step thinking and complex reasoning"
+  - name: "💻 Coding Models"
+    tags: ["codestral", "devstral", "coding"]
+    description: "Specialized for code generation and SWE"
+  - name: "👁️ Vision Models"
+    tags: ["pixtral", "vision"]
+    description: "Multimodal image understanding"
+  - name: "🎤 Audio Models"
+    tags: ["voxtral", "audio"]
+    description: "Speech-to-text and audio chat"
+  - name: "🚀 Edge Models"
+    tags: ["ministral", "edge"]
+    description: "Efficient models for high-volume tasks"
+  - name: "📄 Document AI"
+    tags: ["ocr", "document-ai"]
+    description: "OCR and document processing"
+  - name: "🔍 Embeddings"
+    tags: ["embedding"]
+    description: "Vector embeddings for search and RAG"
+  - name: "🛡️ Safety"
+    tags: ["moderation", "safety"]
+    description: "Content moderation and safety"
+
+# Default model
+default_model: "mistral-large-latest"
+
+# Usage notes
+usage_notes:
+  - "Mistral Large 3 (v25.12): Latest flagship with vision - best quality"
+  - "Magistral models: Use prompt_mode='reasoning' for step-by-step thinking"
+  - "Codestral: Supports FIM (fill-in-middle) for code completion"
+  - "Voxtral: Audio input for chat and transcription"
+  - "OCR: $1 per 1,000 pages for document extraction"
+  - "All chat models support 128k context (except Magistral: 40k)"
+  - "Free tier available for experimentation"