# 🤖 Spec Assistant — MCP-Powered RAG

A local, fully functional developer assistant that brings spec-driven development directly into your IDE. Ask natural language questions about your technical specifications and perform automated code compliance checks directly from VS Code, Claude Desktop or any MCP-compatible client.

---

## Architecture

```
Developer Question / Code Snippet
       │
       ▼
  MCP Server (stdio transport)
  ┌─────────────────────────────┐
  │  get_spec(query)            │  ◄── Custom tools exposed to client
  │  list_specs()               │
  │  validate_code(code, spec)  │
  └────────────┬────────────────┘
               │
        ┌───────▼────────┐
        │  RAG Pipeline  │
        │                │
        │  1. Embed query│──► sentence-transformers (local, all-MiniLM-L6-v2)
        │  2. Retrieve   │──► ChromaDB (local vector DB, cosine metric)
        │  3. Build prompt│
        │  4. Call LLM   │──► Ollama llama3.2 (local) or OpenAI
        └────────────────┘
                │
        ┌───────▼────────┐
        │  specs/ folder │  ◄── Your Markdown (.md) or Text (.txt) files
        └────────────────┘
```

---

## Quick Start

### 1. Prerequisites

- **Python 3.11+** installed on your system.
- **[Ollama](https://ollama.com/download)** installed and running locally.
- Pull the default local model using:
  ```powershell
  ollama pull llama3.2
  ```

### 2. Install Dependencies

Clone this repository, navigate to the directory, and install dependencies:

```powershell
pip install -r requirements.txt
```

> [!NOTE]
> The initial setup might take a moment to resolve as it downloads the local embedding model (`all-MiniLM-L6-v2` ~90MB) on first run.

### 3. Environment Configuration

Copy the example environment configuration to create your local `.env` file:

```powershell
# Windows
copy .env.example .env

# macOS/Linux
cp .env.example .env
```

The defaults are already pre-configured to work with a local Ollama server out of the box.

### 4. Import Specification Documents

Put your `.md` or `.txt` specification documents inside the `specs/` directory. By default, the repository contains:
- `auth_spec.md` — Authentication, authorization rules, and endpoints.
- `user_management_spec.md` — User CRUD API specifications.
- `notification_spec.md` — In-app, webhook, and email notification settings.

### 5. Index Specifications into Vector Store

Run the ingestion pipeline to parse documents, split them into chunks, compute vector embeddings, and save them to your local database:

```powershell
python ingest.py
```

### 6. View Indexed Data

To inspect exactly what text chunks, documents, and metadata are indexed in your local vector database, run the helper database viewer script:

```powershell
python view_db.py
```

---

## Running the MCP Server

### Run server in Dev Mode (with Inspector)

To test the MCP tools interactively, you can run the server using the MCP developer tool:

```powershell
mcp dev mcp_server/server.py
```

This runs the server locally and launches a web-based MCP Inspector where you can invoke and test all tools in real-time.

---

## Integrations

### Connect to Claude Desktop

Add the server configuration to your Claude Desktop configuration file:
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the following JSON configuration (replacing absolute paths with your own directory path):

```json
{
  "mcpServers": {
    "spec-assistant": {
      "command": "python",
      "args": ["C:/absolute/path/to/spec-mcp-poc/mcp_server/server.py"],
      "env": {}
    }
  }
}
```

Restart Claude Desktop, and you will see the new tools symbol in the composer window!

### Connect to IDE Extension (e.g. Cline or Continue in VS Code)

Add this configuration block to your IDE extension configuration file:

```json
{
  "spec-assistant": {
    "command": "python",
    "args": ["mcp_server/server.py"],
    "cwd": "C:/absolute/path/to/spec-mcp-poc"
  }
}
```

---

## Available MCP Tools

| Tool Name | Parameters | Description |
|---|---|---|
| `get_spec` | `query` (str) | Ask natural language questions about specifications. Utilizes semantic vector search to augment your LLM's response. |
| `list_specs` | None | Returns a detailed list of all specifications currently parsed and indexed inside the database. |
| `validate_code` | `code` (str), `spec_name` (str) | Validates code snippets against specifications and returns list of compliant features, violations, and recommendation checklist. |

---

## Project Structure

```
spec-mcp-poc/
├── specs/                    # 📄 Raw specification files (add yours here)
│   ├── auth_spec.md
│   ├── user_management_spec.md
│   └── notification_spec.md
├── ingestion/
│   ├── chunker.py            # Loads specs and splits them into sliding-window text chunks
│   ├── embedder.py           # Embeds chunks using sentence-transformers (local model)
│   └── indexer.py            # Interfaces with ChromaDB (creation, deletes, insertions)
├── rag/
│   ├── retriever.py          # Performs semantic search querying database via cosine distance
│   ├── prompt_builder.py     # Generates LLM chat prompts for retrieval and compliance checks
│   └── llm_client.py         # Routes requests to Ollama (local) or OpenAI (cloud)
├── mcp_server/
│   └── server.py             # MCP Server exposing standard tools over stdio
├── config.py                 # Central configurations and environment reader
├── ingest.py                 # Entry point command line pipeline to run ingestion
├── view_db.py                # Helper utility script to view local vector database entries
├── requirements.txt          # Python dependencies
├── .gitignore                # Git ignored patterns
├── .env                      # Local environment configurations (ignored)
└── .env.example              # Template configuration
```

---

## Switching to Cloud-based OpenAI (Optional)

If you prefer using OpenAI cloud endpoints instead of local Ollama, update your `.env` file configuration:

```env
LLM_BACKEND=openai
OPENAI_API_KEY=sk-proj-your-actual-api-key
OPENAI_MODEL=gpt-4o-mini
```

No code modifications are required; the system automatically switches backends on the fly.

---

## Troubleshooting

| Problem | Potential Cause | Troubleshooting Action |
|---|---|---|
| `No indexed specs found` | Database has not been initialized. | Run `python ingest.py` to index specs. |
| `Connection refused` (Ollama) | Ollama service is not running. | Make sure the Ollama application is running, or run `ollama serve`. |
| `Model not found` | The model is missing in Ollama. | Run `ollama pull llama3.2` to download the model. |
| Slow execution during first run | Cold start downloads. | The local embedding model (`all-MiniLM-L6-v2`) is downloaded once and cached for future runs. |