# pow-mcp-rag-new

A local RAG (Retrieval-Augmented Generation) MCP server for project documentation and code.

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

## Overview

This project provides a Model Context Protocol (MCP) server that indexes project documentation
(specs, headers, source files, PDFs, configs) into a local vector database (ChromaDB) and exposes
semantic search tools to Kiro or any MCP-compatible client.

Supports multiple tech stacks: C/C++, Python, Go, C#, Node.js/TypeScript.

**Distribution name:** `pow-rag-mcp` (unrelated to `rag-mcp` or `rag-mcp-server` packages).

**Minimum Python version:** `3.11` (matches `requires-python = ">=3.11"` in `pyproject.toml`).

Three deployment modes:
- **Docker** (Phase 1) — zero local Python needed; server runs in a container
- **PyPI (recommended for new users)** (Phase 2a) — install via `uvx --from`, `uv tool install`, or `pip install` from PyPI; no repo checkout or local index needed
- **Local PyPI + uvx** (Phase 2b) — install `rag-mcp` via `uvx` from a local package index; no persistent venv, easiest to keep updated. Stepping stone toward a hosted index.
- **pip install** (Phase 2c) — install `rag-mcp` directly into a Python environment.
- **llamaindex** (Phase 3): Using of llamaindex to handle several different data sources.

---

## License

This project is licensed under the Apache 2.0 License — see the [LICENSE](LICENSE) file for details.

## Quick Start

### PyPI (recommended for new users)

Install from PyPI using your preferred method:

**Option 1: One-off execution with `uvx`**
```bash
uvx --from pow-rag-mcp rag-mcp serve
```

**Option 2: Persistent install with `uv tool install`**
```bash
uv tool install pow-rag-mcp
```

**Option 3: Traditional `pip`**
```bash
pip install pow-rag-mcp
```

All three methods fetch `pow-rag-mcp` from PyPI directly — no repository checkout or local package index is required.

See **[doc/PIP_INSTALL_GUIDE.md](doc/PIP_INSTALL_GUIDE.md)** for full details (config seeding, bundled docs, upgrades, and migrating to a hosted index).

### Local PyPI + uvx (recommended for development/publishing workflows)

```bash
cd <your-checkout>/pow-mcp-rag-new
setup-pypi.bat
```

This builds the wheel, publishes it to a local `pypiserver` index (`packages/`), installs it as a
persistent `uv tool` (a stable exe at `~/.local/bin/rag-mcp.exe` — resolved once, not on
every launch), and wires up `~/.kiro/settings/mcp.json` + `.vscode/mcp.json` to launch it directly.
No Docker, no persistent venv to manage. See [TROUBLESHOOTING.md](doc/TROUBLESHOOTING.md) for why
this is preferred over plain `uvx --from` on Windows with this package's large dependency tree.

**Full guide:** [doc/PIP_INSTALL_GUIDE.md](doc/PIP_INSTALL_GUIDE.md#local-pypi-uvx-mode)


### Docker (alternative)

```bash
cd <your-checkout>/pow-mcp-rag-new
docker build -t rag-mcp-new-pip:latest .

# Index your projects (set SRC to your repos folder)
$SRC = "C:/Users/you/GIT"   # PowerShell
docker run --rm -v "${SRC}:/projects:ro" -v rag-mcp-new-pip-data:/app/data rag-mcp-new-pip:latest python indexer.py
```

Then add to `~/.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "rag-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "C:/Users/you/GIT:/projects:ro",
        "-v", "rag-mcp-new-pip-data:/app/data",
        "rag-mcp-new-pip:latest",
        "python", "server.py", "--no-reindex"
      ],
      "disabled": false,
      "autoApprove": [
        "search_docs", "search_specs", "search_code", "search_logs",
        "list_projects", "list_files", "get_document", "get_project_summary",
        "find_function", "find_variable", "search_hex_pattern", "compare_projects",
        "add_project", "add_file", "add_folder", "add_pattern", "index_log_file"
      ]
    }
  }
}
```

Restart Kiro — the RAG is ready. **Full guide:** [doc/DOCKER_GUIDE.md](doc/DOCKER_GUIDE.md)
(project management, HTTP server, `docker run` CLI reference, `setup-docker.bat` automation).

### pip install (hosted index, once available)

```bash
pip install torch --index-url https://download.pytorch.org/whl/cpu
rag-mcp config   # seeds config on first run, shows resolved paths
rag-mcp index
rag-mcp serve
```

**Full guide:** [doc/PIP_INSTALL_GUIDE.md](doc/PIP_INSTALL_GUIDE.md)

---

## Documentation

> **Reading this from `pip show` / a package-index page instead of the repo?** This README's
> links are relative paths into the `pow-mcp-rag-new` repo (GitHub/clone) and won't resolve from
> an installed package alone. Three docs travel with the install and are available offline via
> `rag-mcp docs <name>` (see table below); the rest require the repo checkout.

| Guide | Covers | Bundled in package? |
|---|---|---|
| [doc/DOCKER_GUIDE.md](doc/DOCKER_GUIDE.md) | Full Docker setup, adding/removing projects, HTTP server, complete CLI reference (Docker mode) | No — repo only |
| [doc/PIP_INSTALL_GUIDE.md](doc/PIP_INSTALL_GUIDE.md) | Local PyPI + uvx setup, pip installation, config seeding, building/publishing the wheel| No — repo only |
| [doc/ARCHITECTURE.md](doc/ARCHITECTURE.md) | How indexing/retrieval works, embedding model, PDF handling, file structure | No — repo only |
| [doc/CLI_REFERENCE.md](doc/CLI_REFERENCE.md) | Full `rag-mcp` CLI reference: `serve`/`index`/`config`/`docs`, all flags and env vars | **Yes** — `rag-mcp docs cli` |
| [doc/TOOLS_GUIDE.md](doc/TOOLS_GUIDE.md) | Full MCP tool reference (21 tools) with usage examples | **Yes** — `rag-mcp docs tools` |
| [doc/LOG_INDEXING_GUIDE.md](doc/LOG_INDEXING_GUIDE.md) | Structured log indexing usage guide | **Yes** — `rag-mcp docs log-indexing` |
| [doc/LOG_PATTERN_CONFIGURATION.md](doc/LOG_PATTERN_CONFIGURATION.md) | How to write pattern configs for new log formats | **Yes** — `rag-mcp docs log-patterns` |
| [doc/TROUBLESHOOTING.md](doc/TROUBLESHOOTING.md) | Common issues and fixes | No — repo only |

Run `rag-mcp docs` with no arguments to list the bundled docs from any install (pip, uvx,
or `uv tool install`) without needing the repo.

## What gets indexed

File types are configured in `config.yaml` under `index_extensions`. By default: C/C++, Python,
React/JS/TS, C#, Go, Kotlin, Markdown, PDF, text. Directories in `excluded_dirs` (build,
node_modules, `.git`, ...) are skipped. See [doc/DOCKER_GUIDE.md](doc/DOCKER_GUIDE.md#what-gets-indexed)
for details on configuring projects and adding new sources.

## MCP Tools

Once configured, 21 MCP tools are available for searching, browsing, and managing your indexed
projects — see **[doc/TOOLS_GUIDE.md](doc/TOOLS_GUIDE.md)** for the full list with examples
(also available offline: `rag-mcp docs tools`).

Key tools:
- `search_docs` / `search_specs` / `search_code` — semantic search, scoped by file type
- `search_hex_pattern`, `find_function`, `find_variable` — exact text matching for codes/symbols
- `search_logs`, `index_log_file` — structured log search and on-demand indexing
- `add_project`, `add_pattern`, `remove_project` — index management from Kiro chat

## Log Indexing

Structured log indexing with severity filtering, time-window search, and hex error-code
matching. The pipeline is fully generic — driven by YAML pattern configs, so any log format
can be supported without code changes. See [doc/DOCKER_GUIDE.md](doc/DOCKER_GUIDE.md#log-indexing)
and [doc/LOG_INDEXING_GUIDE.md](doc/LOG_INDEXING_GUIDE.md) (also: `rag-mcp docs log-indexing`).

## Need Help?

See [doc/TROUBLESHOOTING.md](doc/TROUBLESHOOTING.md) for common issues, including:
- MCP server hangs on startup
- Stale search results after re-indexing
- `entrypoint.sh` exec errors from CRLF line endings
- `--project <NAME>` silently doing nothing
- Concurrent query errors