source-mcp 0.1.3b1__tar.gz

source_mcp-0.1.3b1/.env.example

@@ -0,0 +1,15 @@
+# RMCP Environment Configuration
+# Copy this to .env and fill in your values
+
+# Provider: "fastembed" or "openai"
+EMBEDDING_PROVIDER=openai
+
+# OpenAI API Key (Required for openai provider)
+OPENAI_API_KEY=your_key_here
+
+# Optional: Override default models
+# EMBEDDING_MODEL=text-embedding-3-small
+# EMBEDDING_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
+
+# Storage Path
+ZVEC_PATH=./zvec_db

source_mcp-0.1.3b1/.gitignore

@@ -0,0 +1,77 @@
+# General
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+*.log
+
+# Python-generated files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.python-version
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# IDEs and Editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+*.sublime-project
+*.sublime-workspace
+
+# Testing, Linting and Coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+nosetests.xml
+
+# Jupyter Notebooks
+.ipynb_checkpoints
+
+# Project Specific Data (Local State)
+zvec_db/
+.rmcp/
+.rmcp_manifest.json
+artifacts/

source_mcp-0.1.3b1/GEMINI.md

@@ -0,0 +1,62 @@
+# Source-MCP (formerly RAG-MCP) - Gemini Instructions & Guide
+
+This file contains useful instructions and summaries of changes made during our sessions.
+
+## 🚀 How to Run
+
+### Manual Run (Terminal)
+
+Ensure you have `uv` installed.
+
+```bash
+# Set required environment variables
+export EMBEDDING_PROVIDER="openai" # or "fastembed"
+export OPENAI_API_KEY="sk-..."    # required for openai
+export ZVEC_PATH="./zvec_db"      # optional override
+
+uv run python -m src.main --path .
+```
+
+### Environment Variables (`.env`)
+
+You can create a `.env` file in the root directory:
+
+```bash
+EMBEDDING_PROVIDER=openai
+OPENAI_API_KEY=your_key
+ZVEC_PATH=./zvec_db
+```
+
+## 🛠 Features
+
+### 1. OpenAI & FastEmbed Support
+
+- **OpenAI**: Defaults to `text-embedding-3-small` (1536 dims).
+- **FastEmbed**: Defaults to `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` (384 dims, multilingual).
+- **Auto-Migration**: If you change providers/models and the vector dimension changes, the service detects it via `meta.json` in the DB folder and **automatically recreates** the index.
+
+### 2. Incremental Indexing
+
+- Uses `.source-mcp_manifest.json` to store file fingerprints (mtime + size).
+- Only indexes new or modified files on startup.
+
+### 3. Web Dashboard (Port 8000)
+
+- **Live Logs**: Includes an **Auto-scroll toggle** (click the pulse indicator).
+- **Reindex Base**: A red button to force-wipe the DB and manifest for a fresh full scan.
+- **Search Debug**: Special endpoint `/api/search/debug?q=...` to see raw scores.
+
+## 🧪 Testing
+
+```bash
+uv run python -m pytest tests/ -v
+```
+
+## 📝 Configuration
+
+- `src/config.py`: Contains default settings.
+- `mcp_config.json`: Use this to configure Source-MCP as an MCP server for Gemini/Claude.
+
+## Communication Language
+
+- ALL interactions, explanations, and commit messages MUST be in Russian unless explicitly requested otherwise.

source_mcp-0.1.3b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Source-MCP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

source_mcp-0.1.3b1/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: source-mcp
+Version: 0.1.3b1
+Summary: A Model Context Protocol (MCP) server for semantic search and Retrieval-Augmented Generation (RAG) over local codebases and documents.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.129.0
+Requires-Dist: fastembed>=0.7.4
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: mcp[cli]>=1.26.0
+Requires-Dist: openai>=2.21.0
+Requires-Dist: pathspec>=1.0.4
+Requires-Dist: python-multipart>=0.0.22
+Requires-Dist: uvicorn>=0.41.0
+Requires-Dist: watchdog>=6.0.0
+Requires-Dist: zvec>=0.2.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <h1>🔍 Source-MCP</h1>
+  <p><strong>A Model Context Protocol (MCP) server for semantic search and Retrieval-Augmented Generation (RAG) over local codebases and documents.</strong></p>
+</div>
+
+---
+
+## 📖 Overview
+
+**Source-MCP** leverages the [Model Context Protocol](https://modelcontextprotocol.io) to provide AI assistants (like Claude, Gemini, and others) with direct access to local files through semantic search.
+
+Instead of manually copy-pasting code or documentation into your prompts, Source-MCP automatically indexes your local repository, generates vector embeddings, and enables the AI to semantically search and retrieve only the most relevant files.
+
+## ✨ Key Features
+
+- **Dual Embedding Support:**
+  - **OpenAI:** Uses robust `text-embedding-3-small` (1536 dimensions) for high-quality enterprise embeddings.
+  - **FastEmbed (Local):** Uses `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` (384 dims). Runs entirely locally, no API keys required, and supports multilingual inquiries.
+- **Smart Incremental Indexing:** Uses file fingerprints (modified time + size) to only index new or modified files, ensuring lightning-fast startup times.
+- **Auto-Migration:** Automatically detects embedding dimension changes (e.g., switching from OpenAI to FastEmbed) and safely recreates the vector index.
+- **Web Dashboard (Port 8000):**
+  - **Live Logs:** View real-time indexing and search activity with auto-scroll.
+  - **Reindex Base:** Force-wipe the vector DB and manifest for a completely fresh full scan.
+  - **Reindex Base:** Force-wipe the vector DB and manifest for a completely fresh full scan.
+  - **Search Debugging:** Special endpoint (`/api/search/debug?q=...`) to test raw semantic search scores.
+
+## 🤔 Why local embeddings and `zvec`?
+
+We use [**zvec**](https://github.com/alibaba/zvec), a lightweight, high-performance vector database maintained by Alibaba. `zvec` is embedded directly into the Python process, eliminating the need to set up or run external vector servers (like Pinecone, Milvus, or Qdrant). Combined with `FastEmbed`, this allows Source-MCP to build the entire semantic search pipeline **fully offline**, quickly, and entirely on your local machine.
+
+## 🚀 Installation & Setup
+
+1. **Prerequisites:** Ensure you have Python 3.10+ and [`uv`](https://github.com/astral-sh/uv) installed.
+2. **Clone the repository:**
+
+   ```bash
+   git clone https://github.com/AlexShimmy/source-mcp.git
+   cd source-mcp
+   ```
+
+3. **Install Dependencies:**
+
+   ```bash
+   # uv will automatically handle virtual environment creation and dependencies
+   uv sync
+   ```
+
+## ⚙️ Configuration
+
+Create a `.env` file in the root directory (you can copy `.env.example` if available).
+
+```bash
+# Choose your provider: "openai" or "fastembed"
+EMBEDDING_PROVIDER=openai
+
+# Required ONLY if using OpenAI
+# Required ONLY if using OpenAI
+OPENAI_API_KEY=sk-your-openai-api-key
+
+# Optional: Path to store the vector database (Defaults to `.source-mcp/zvec_db` in the index dir)
+ZVEC_PATH=./zvec_db
+
+# Optional: Which directory to index (Defaults to current directory)
+SOURCE_MCP_INDEX_DIR=/path/to/your/project
+
+# Optional: Port for the Web Dashboard (Defaults to 8000)
+WEB_PORT=8000
+```
+
+## 🖱️ Usage
+
+### Running Manually (Terminal & Dashboard)
+
+To start the MCP server manually and access the web dashboard:
+
+```bash
+uv run python -m src.main --path .
+```
+
+- The **MCP protocol** will listen on `stdio`.
+- The **Web Dashboard** will be available at [http://localhost:8000](http://localhost:8000).
+
+### 🔌 MCP Configuration
+
+The config is the same for all clients (Claude Desktop, Cursor, VS Code / Cline, etc.):
+
+```json
+{
+  "mcpServers": {
+    "source-mcp": {
+      "command": "uv",
+      "args": ["--directory", "/absolute/path/to/source-mcp", "run", "python", "-m", "src.main"]
+    }
+  }
+}
+```
+
+All other settings (such as `SOURCE_MCP_INDEX_DIR`, `EMBEDDING_PROVIDER` or `OPENAI_API_KEY`) should be configured via the `.env` file in the root directory of Source-MCP.
+
+## 🧪 Testing
+
+The project uses `pytest` for unit and end-to-end tests. To run the test suite:
+
+```bash
+uv run python -m pytest tests/ -v
+```
+
+## 📜 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

source_mcp-0.1.3b1/README.md

@@ -0,0 +1,110 @@
+<div align="center">
+  <h1>🔍 Source-MCP</h1>
+  <p><strong>A Model Context Protocol (MCP) server for semantic search and Retrieval-Augmented Generation (RAG) over local codebases and documents.</strong></p>
+</div>
+
+---
+
+## 📖 Overview
+
+**Source-MCP** leverages the [Model Context Protocol](https://modelcontextprotocol.io) to provide AI assistants (like Claude, Gemini, and others) with direct access to local files through semantic search.
+
+Instead of manually copy-pasting code or documentation into your prompts, Source-MCP automatically indexes your local repository, generates vector embeddings, and enables the AI to semantically search and retrieve only the most relevant files.
+
+## ✨ Key Features
+
+- **Dual Embedding Support:**
+  - **OpenAI:** Uses robust `text-embedding-3-small` (1536 dimensions) for high-quality enterprise embeddings.
+  - **FastEmbed (Local):** Uses `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` (384 dims). Runs entirely locally, no API keys required, and supports multilingual inquiries.
+- **Smart Incremental Indexing:** Uses file fingerprints (modified time + size) to only index new or modified files, ensuring lightning-fast startup times.
+- **Auto-Migration:** Automatically detects embedding dimension changes (e.g., switching from OpenAI to FastEmbed) and safely recreates the vector index.
+- **Web Dashboard (Port 8000):**
+  - **Live Logs:** View real-time indexing and search activity with auto-scroll.
+  - **Reindex Base:** Force-wipe the vector DB and manifest for a completely fresh full scan.
+  - **Reindex Base:** Force-wipe the vector DB and manifest for a completely fresh full scan.
+  - **Search Debugging:** Special endpoint (`/api/search/debug?q=...`) to test raw semantic search scores.
+
+## 🤔 Why local embeddings and `zvec`?
+
+We use [**zvec**](https://github.com/alibaba/zvec), a lightweight, high-performance vector database maintained by Alibaba. `zvec` is embedded directly into the Python process, eliminating the need to set up or run external vector servers (like Pinecone, Milvus, or Qdrant). Combined with `FastEmbed`, this allows Source-MCP to build the entire semantic search pipeline **fully offline**, quickly, and entirely on your local machine.
+
+## 🚀 Installation & Setup
+
+1. **Prerequisites:** Ensure you have Python 3.10+ and [`uv`](https://github.com/astral-sh/uv) installed.
+2. **Clone the repository:**
+
+   ```bash
+   git clone https://github.com/AlexShimmy/source-mcp.git
+   cd source-mcp
+   ```
+
+3. **Install Dependencies:**
+
+   ```bash
+   # uv will automatically handle virtual environment creation and dependencies
+   uv sync
+   ```
+
+## ⚙️ Configuration
+
+Create a `.env` file in the root directory (you can copy `.env.example` if available).
+
+```bash
+# Choose your provider: "openai" or "fastembed"
+EMBEDDING_PROVIDER=openai
+
+# Required ONLY if using OpenAI
+# Required ONLY if using OpenAI
+OPENAI_API_KEY=sk-your-openai-api-key
+
+# Optional: Path to store the vector database (Defaults to `.source-mcp/zvec_db` in the index dir)
+ZVEC_PATH=./zvec_db
+
+# Optional: Which directory to index (Defaults to current directory)
+SOURCE_MCP_INDEX_DIR=/path/to/your/project
+
+# Optional: Port for the Web Dashboard (Defaults to 8000)
+WEB_PORT=8000
+```
+
+## 🖱️ Usage
+
+### Running Manually (Terminal & Dashboard)
+
+To start the MCP server manually and access the web dashboard:
+
+```bash
+uv run python -m src.main --path .
+```
+
+- The **MCP protocol** will listen on `stdio`.
+- The **Web Dashboard** will be available at [http://localhost:8000](http://localhost:8000).
+
+### 🔌 MCP Configuration
+
+The config is the same for all clients (Claude Desktop, Cursor, VS Code / Cline, etc.):
+
+```json
+{
+  "mcpServers": {
+    "source-mcp": {
+      "command": "uv",
+      "args": ["--directory", "/absolute/path/to/source-mcp", "run", "python", "-m", "src.main"]
+    }
+  }
+}
+```
+
+All other settings (such as `SOURCE_MCP_INDEX_DIR`, `EMBEDDING_PROVIDER` or `OPENAI_API_KEY`) should be configured via the `.env` file in the root directory of Source-MCP.
+
+## 🧪 Testing
+
+The project uses `pytest` for unit and end-to-end tests. To run the test suite:
+
+```bash
+uv run python -m pytest tests/ -v
+```
+
+## 📜 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

source_mcp-0.1.3b1/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "source-mcp"
+version = "0.1.3b1"
+description = "A Model Context Protocol (MCP) server for semantic search and Retrieval-Augmented Generation (RAG) over local codebases and documents."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.129.0",
+    "fastembed>=0.7.4",
+    "jinja2>=3.1.6",
+    "mcp[cli]>=1.26.0",
+    "openai>=2.21.0",
+    "pathspec>=1.0.4",
+    "python-multipart>=0.0.22",
+    "uvicorn>=0.41.0",
+    "watchdog>=6.0.0",
+    "zvec>=0.2.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+
+
+[project.scripts]
+source-mcp = "src.main:main"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+]

source_mcp-0.1.3b1/src/config.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+import os
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    docs_path: str = os.getenv("SOURCE_MCP_INDEX_DIR", ".")
+    zvec_path: str = "./zvec_db"
+    
+    # Embedding settings
+    embedding_provider: str = "fastembed"  # "fastembed" or "openai"
+    # FastEmbed model (384 dims)
+    # embedding_model: str = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
+    # OpenAI model (1536 dims for text-embedding-3-small)
+    embedding_model: str | None = None
+    openai_api_key: str | None = None
+
+    # Web Dashboard settings
+    web_port: int = 8000
+    host: str = "127.0.0.1"
+
+
+settings = Settings()

source_mcp-0.1.3b1/src/main.py

@@ -0,0 +1,163 @@
+import sys
+import os
+import argparse
+import threading
+import webbrowser
+from pathlib import Path
+
+import uvicorn
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+
+from .config import settings
+from .services.indexer import indexer
+from .services.monitor import logger, monitor
+from .web.app import app as web_app
+
+# ── MCP Server ──────────────────────────────────────────────
+mcp = FastMCP("Source-MCP Local RAG Server")
+
+
+@mcp.tool()
+async def search_knowledge_base(query: str, limit: int = 5) -> str:
+    """
+    Search for relevant context in the indexed documents.
+
+    Args:
+        query: The question or topic to search for.
+        limit: Maximum number of text chunks to return.
+    """
+    logger.info(f"Received search query: {query}")
+    results = indexer.query(query, limit)
+
+    if not results:
+        return "No relevant information found in the local knowledge base."
+
+    formatted_results = "\n\n---\n\n".join(results)
+    return f"Found {len(results)} relevant chunks:\n\n{formatted_results}"
+
+
+@mcp.tool()
+async def get_index_stats() -> str:
+    """Get current statistics about the vector index."""
+    stats = indexer.get_stats()
+    return str(stats)
+
+
+# ── Background services ────────────────────────────────────
+def start_background_services():
+    logger.info("Starting background services...")
+    indexer.start_watching()
+    threading.Thread(target=indexer.index_directory, daemon=True).start()
+
+
+def run_dashboard():
+    """Run the FastAPI dashboard in a separate thread."""
+    logger.info(f"Starting Dashboard at http://{settings.host}:{settings.web_port}")
+    config = uvicorn.Config(
+        web_app,
+        host=settings.host,
+        port=settings.web_port,
+        log_level="error",
+    )
+    server = uvicorn.Server(config)
+    server.run()
+
+
+# ── CLI entry-point ─────────────────────────────────────────
+def main():
+    parser = argparse.ArgumentParser(description="Source-MCP Server")
+    parser.add_argument("--path", type=str, help="Path to the documents directory")
+    parser.add_argument("--embed-model", type=str, help="HuggingFace embedding model name")
+    parser.add_argument("--web-port", type=int, help="Port for the Web Dashboard")
+    parser.add_argument("--no-browser", action="store_true", help="Don't auto-open browser")
+
+    args, _unknown = parser.parse_known_args()
+
+    # Determine project root
+    if args.path:
+        project_path = Path(args.path).resolve()
+    elif os.getenv("SOURCE_MCP_INDEX_DIR"):
+        project_path = Path(os.getenv("SOURCE_MCP_INDEX_DIR")).resolve()
+    else:
+        project_path = Path(".").resolve()
+
+    # Load environment from project root (override existing env vars)
+    env_path = project_path / ".env"
+    if env_path.exists():
+        logger.info(f"Loading environment from {env_path}")
+        load_dotenv(env_path, override=True)
+    
+    # Update settings from environment (pydantic settings are already init, so we update manually)
+    settings.docs_path = str(project_path)
+    
+    # Use project-local storage for index
+    sourcemcp_dir = project_path / ".source-mcp"
+    settings.zvec_path = str(sourcemcp_dir / "zvec_db")
+    
+    # Update config from env vars if present
+    if os.getenv("EMBEDDING_PROVIDER"):
+        settings.embedding_provider = os.getenv("EMBEDDING_PROVIDER")
+    if os.getenv("EMBEDDING_MODEL"):
+        settings.embedding_model = os.getenv("EMBEDDING_MODEL")
+    if os.getenv("OPENAI_API_KEY"):
+        settings.openai_api_key = os.getenv("OPENAI_API_KEY")
+    if os.getenv("WEB_PORT"):
+        settings.web_port = int(os.getenv("WEB_PORT"))
+
+    # CLI overrides env
+    if args.embed_model:
+        settings.embedding_model = args.embed_model
+    if args.web_port:
+        settings.web_port = args.web_port
+
+    logger.info(f"Project path: {settings.docs_path}")
+    logger.info(f"Index path: {settings.zvec_path}")
+
+    # Ensure directories exist
+    Path(settings.docs_path).mkdir(parents=True, exist_ok=True)
+    Path(settings.zvec_path).mkdir(parents=True, exist_ok=True)
+
+    # Initialize indexer (delayed to avoid side-effects on import)
+    try:
+        indexer.configure()
+        indexer.initialize()
+    except Exception as e:
+        logger.error(f"Failed to initialize indexer: {e}")
+        sys.exit(1)
+
+    # Start dashboard
+    threading.Thread(target=run_dashboard, daemon=True).start()
+
+    # Auto-open browser (with delay for server startup)
+    if not args.no_browser:
+        def open_browser():
+            import time
+            time.sleep(1.5)
+            url = f"http://{settings.host}:{settings.web_port}"
+            logger.info(f"Opening dashboard in browser: {url}")
+            try:
+                webbrowser.open(url)
+            except Exception:
+                pass
+
+        threading.Thread(target=open_browser, daemon=True).start()
+
+    # Start indexer & watcher
+    start_background_services()
+
+    # Run MCP server (blocks)
+    try:
+        mcp.run(transport="stdio")
+    except KeyboardInterrupt:
+        logger.info("Server stopping...")
+    except Exception as e:
+        logger.error(f"MCP Server error: {e}")
+        sys.exit(1)
+    finally:
+        logger.info("Stopping indexer watcher...")
+        indexer.stop_watching()
+
+
+if __name__ == "__main__":
+    main()