ai-odoofinder-mcp 1.0.0
MCP Server for AI-OdooFinder - Semantic search for Odoo modules in the OCA ecosystem
Requires Python: >=3.11
Keywords: ai, claude, llm, mcp, oca, odoo, search, semantic-search

# AI-OdooFinder MCP Server

**Language**: [English](README.md) | [Español](README.es.md)

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](../README.md#installation).

Basic configuration:

```json
{
  "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](https://docs.astral.sh/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:**
```json
{
  "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

```bash
# 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)

```bash
# 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:**
   ```bash
   uv --version
   ```

2. **Check Python version:**
   ```bash
   python --version  # Should be 3.11+
   ```

3. **Reinstall dependencies:**
   ```bash
   uv sync --reinstall
   ```

### Connection to API fails

1. **Verify API is accessible:**
   ```bash
   curl https://strategy-orchestrator-prod.tailf7d690.ts.net/health
   ```

2. **Check timeout settings:**
   ```bash
   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:

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

To publish to PyPI (future):

```bash
cd mcp-server
uv build
uv publish
```

---

## Related Documentation

- [Main Project README](../README.md) - User installation guide
- [Backend API Documentation](../backend/README.md) - FastAPI backend REST API
- [CHANGELOG](../docs/en/CHANGELOG.md) - Version history
- [MCP Protocol](https://modelcontextprotocol.io/) - Official MCP docs
- [FastMCP](https://github.com/jlowin/fastmcp) - Framework used

---

## License

MIT - See [LICENSE](../LICENSE)