AI-OdooFinder MCP Server

Language: English | Español

MCP (Model Context Protocol) server for semantic search of Odoo modules in the OCA ecosystem.

Overview

This MCP server provides a tool called search_odoo_modules that enables LLMs to search through 16,494 indexed Odoo modules from OCA repositories using hybrid search (semantic + BM25).

Quick Start

For installation instructions, see the main project README.

Basic configuration:

{
  "mcpServers": {
    "ai-odoofinder": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/SantipBarber/ai-odoo-finder#subdirectory=mcp-server",
        "ai-odoofinder-mcp"
      ],
      "env": {
        "AI_ODOOFINDER_API_URL": "https://strategy-orchestrator-prod.tailf7d690.ts.net"
      }
    }
  }
}

Note: Requires uv package manager installed.

---

Features

• Hybrid Search: Combines semantic search (embeddings) with BM25 full-text
• Version Filtering: Only shows compatible modules (Odoo 10.0 to 19.0)
• AI Enrichment: Descriptions, tags, and keywords generated by Grok-4-fast
• Intelligent Flow: Smart clarifications, query expansion, confidence levels

---

Architecture

┌─────────────────┐
│   MCP Client    │ (Claude Desktop, Zed, Cursor, etc.)
│   (STDIO/HTTP)  │
└────────┬────────┘
         │
         │ JSON-RPC / SSE
         │
┌────────▼────────┐
│   MCP Server    │ (This component)
│  FastMCP + uv   │
└────────┬────────┘
         │
         │ HTTPS
         │
┌────────▼────────┐
│   Backend API   │ (FastAPI + PostgreSQL)
│   :8989         │
└─────────────────┘

Two modes:

• STDIO: For local clients (Claude Desktop)
• HTTP/SSE: For remote clients (Claude.ai Web, requires port 8080)

---

Tools

search_odoo_modules

Search for Odoo modules using natural language queries.

Parameters:

• query (string, required): Search query in natural language
• version (string, required): Odoo version (e.g., "16.0", "17.0")
• limit (integer, optional): Max results (default: 10, max: 50)
• dependencies (string, optional): Filter by dependencies (comma-separated)

Returns:

• Structured JSON with modules, confidence level, and guidance

Example:

{
  "query": "electronic invoicing for Spain",
  "version": "16.0",
  "limit": 5
}

---

Intelligent Search Flow

The server implements an intelligent search flow:

1. Clarification: Asks for details if query is generic or missing version
2. Query Expansion: Adds ES/EN synonyms, localization prefixes (l10n_XX_)
3. Structured Response: Returns results with confidence levels:
   • HIGH (score ≥80): Detailed format with recommendations
   • MEDIUM (50-79): Summary format with alternatives
   • LOW (<50): Suggestions to refine search
4. Confirmation: Validates with user if found what they were looking for

---

Environment Variables

Variable	Default	Description
AI_ODOOFINDER_API_URL	http://localhost:8989	Backend API URL
AI_ODOOFINDER_API_TIMEOUT	60	API timeout in seconds

---

Project Structure

mcp-server/
├── pyproject.toml           # Package configuration (uvx installable)
├── README.md                # This file
└── src/
    └── ai_odoofinder_mcp/
        ├── __init__.py
        └── server.py        # Main MCP server (FastMCP)

---

Development

Local Testing

# Install dependencies
cd mcp-server
uv sync

# Run server (STDIO mode)
uv run ai-odoofinder-mcp

# Test with MCP Inspector
npx @modelcontextprotocol/inspector uv run ai-odoofinder-mcp

HTTP Mode (for remote clients)

# Run with HTTP transport
uv run ai-odoofinder-mcp --http --port 8080

---

API Integration

The MCP server connects to the FastAPI backend at the URL specified in AI_ODOOFINDER_API_URL.

Backend endpoints used:

• GET /api/v1/search - Hybrid search
• GET /health - Health check

Search algorithm:

1. Generate embedding for query (Qwen3-Embedding-4B)
2. Vector search (pgvector HNSW)
3. BM25 full-text search (PostgreSQL tsvector)
4. Combine results with Reciprocal Rank Fusion (RRF)

RRF_score = 1/(k + rank_vector) + 1/(k + rank_bm25)

Where k=60 (standard RRF constant)

---

Troubleshooting

Server doesn't start

1. Check uv is installed:

   uv --version
   

2. Check Python version:

   python --version  # Should be 3.11+
   

3. Reinstall dependencies:

   uv sync --reinstall
   

Connection to API fails

1. Verify API is accessible:

   curl https://strategy-orchestrator-prod.tailf7d690.ts.net/health
   

2. Check timeout settings:

   export AI_ODOOFINDER_API_TIMEOUT=120
   

MCP client doesn't see the tool

1. Check MCP client logs for connection errors
2. Verify JSON-RPC is working: Use MCP Inspector
3. Restart MCP client completely

---

Publishing

The MCP server is installable via uvx directly from Git:

uvx --from git+https://github.com/SantipBarber/ai-odoo-finder#subdirectory=mcp-server ai-odoofinder-mcp

To publish to PyPI (future):

cd mcp-server
uv build
uv publish

---

Related Documentation

• Main Project README - User installation guide
• Backend API Documentation - FastAPI backend REST API
• CHANGELOG - Version history
• MCP Protocol - Official MCP docs
• FastMCP - Framework used

---

License

MIT - See LICENSE