Odyssey Project

Odyssey is a project designed to provide real-time synchronization, semantic chunking, and user-friendly project path configuration. It consists of a Python AI engine for indexing and searching, and a Node.js MCP server for real-time file monitoring.

Features

• Real-time Synchronization (Phase 3): Monitors file changes (create/update/delete) in a specified folder and updates the index in real-time.
• Semantic Chunking (Phase 4): Chunks documents into semantic units (paragraphs, sections) for improved search accuracy and source citation.
• User Experience Enhancement (Phase 5): Provides a user-friendly way to configure project paths, either via a GUI or a terminal prompt.

Project Components

• MCP Server: A Node.js based server responsible for real-time file monitoring.
• Python AI Engine: Handles document indexing and searching.

Installation

Prerequisites

• Node.js (LTS version recommended)
• Python 3.8+

Steps

1. Install the Odyssey MCP Server:

   npm install -g odyssey-mcp-server
   # Or use npx for direct execution without global installation:
   # npx odyssey-mcp-server

2. Automatic Python Environment Setup: The server will automatically set up a Python virtual environment and install necessary dependencies upon its first run. Ensure you have python3 and pip installed and accessible in your system's PATH.

Usage

Starting the MCP Server

npx odyssey-mcp-server
# Or with project path:
# npx odyssey-mcp-server --projectPath /path/to/your/project

Running Python Scripts

(Further instructions for running indexer.py and searcher.py will be added here based on their CLI arguments or API.)

Configuration

The MCP server requires a project directory to monitor and index. You must provide the project path using either the --projectPath command-line argument or the ODYSSEY_PROJECT_PATH environment variable.

1. Environment Variable (Recommended for MCP Clients)

This method is recommended when integrating with MCP clients like Cursor or Claude, as it keeps the args array clean.

Example mcpServers configuration for Cursor/Claude:

{
  "mcpServers": {
    "Odyssey": {
      "command": "npx",
      "args": [
        "odyssey-mcp-server"
      ],
      "env": {
        "ODYSSEY_PROJECT_PATH": "/path/to/your/project/to/index"
      }
    }
  }
}

2. Command-Line Argument

You can also pass the project path as a command-line argument when starting the server:

npx odyssey-mcp-server --projectPath /path/to/your/project