IVD

---

The Problem

AI agents hallucinate not because they're bad — but because you're feeding the wrong knowledge system.

Research shows LLMs rely primarily on contextual knowledge (the prompt) over parametric knowledge (training data) — but only when the context is structured and precise (Huang et al., ICLR 2024; 9-LLM contextual vs. parametric study, 2024). When you give vague prose — a PRD, a user story, a chat message — the context channel is underloaded. The model fills the gaps from training. Those gaps are the hallucinations.

Without IVD                              With IVD

You: "Add CSV export"                    You: "Add CSV export for compliance"
AI:  [builds with wrong columns]         AI:  [writes intent.yaml with constraints]
You: "No, these columns, ISO dates"      You:  "Yes, that's what I meant"
AI:  [rewrites, still wrong]             AI:  [implements, verifies against constraints]
You: "Still not right..."                You:  "Done. First try."
  Many turns. Many hallucinations.         One turn. Mismatches caught by the constraint check, not by you.

IVD saturates the contextual channel with structured, verifiable intent — so the model has nothing to guess.

---

Quick Start

Works locally. No API key required. Under 5 minutes.

0. See it work first (30 seconds, no setup)

git clone https://github.com/leocelis/ivd.git && cd ivd
python3 examples/intent_demo/run_demo.py

Runs offline. Shows a vague prompt producing a hallucinated implementation, then the same request run against a structured intent artifact — with the constraint check catching the mismatch before you'd ever see it. This is the core loop this README is about; everything below is how to wire it into your own agent.

1. Clone and setup

git clone https://github.com/leocelis/ivd.git
cd ivd
./mcp_server/devops/setup.sh    # creates .venv, installs all deps

2. Add to your IDE

Important: command must point at the venv's Python — setup.sh installs IVD's dependencies into .venv/, not your system Python. Using "command": "python" here will fail with ModuleNotFoundError. Replace /path/to/ivd with your actual clone path.

Cursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "ivd": {
      "command": "/path/to/ivd/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/path/to/ivd",
      "env": {
        "PYTHONPATH": "/path/to/ivd",
        "LOG_DIR": "/path/to/ivd/mcp_server/logs"
      }
    }
  }
}

VS Code / GitHub Copilot (.vscode/mcp.json):

{
  "servers": {
    "ivd": {
      "type": "stdio",
      "command": "/path/to/ivd/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/path/to/ivd",
      "env": {
        "PYTHONPATH": "/path/to/ivd",
        "LOG_DIR": "/path/to/ivd/mcp_server/logs"
      }
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ivd": {
      "command": "/path/to/ivd/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/path/to/ivd",
      "env": {
        "PYTHONPATH": "/path/to/ivd",
        "LOG_DIR": "/path/to/ivd/mcp_server/logs"
      }
    }
  }
}

Claude Code:

claude mcp add ivd -e PYTHONPATH=/path/to/ivd -e LOG_DIR=/path/to/ivd/mcp_server/logs -- /path/to/ivd/.venv/bin/python -m mcp_server.server

PYTHONPATH lets the server start when a client ignores cwd (Cursor and Claude Desktop do not document it). LOG_DIR keeps logs inside the clone, so the server also starts when the client launches it from a read-only folder.

A pyproject.toml now ships in the repo (pip install . or pip install -e . gives you an ivd-mcp console command). A PyPI release (uvx ivd-mcp, no clone required) is planned — see ROADMAP.md.

3. Use it

Ask your AI agent to use IVD tools. For example:

• "Use ivd_get_context to learn about the IVD framework"
• "Use ivd_scaffold to create an intent for my user authentication module"
• "Use ivd_validate to check my intent artifact"

That's it. 32 of 33 tools work immediately with zero configuration — only ivd_search needs an OPENAI_API_KEY.

4. Enable semantic search (optional)

ivd_search requires embeddings. Generate them once (~$0.01, under a minute):

export OPENAI_API_KEY=your-key
./mcp_server/devops/embed.sh

---

How It Works

1. You describe      →  what you want (natural language)
2. AI writes         →  structured intent artifact (YAML with constraints and tests)
3. You review        →  "Is this what I meant?" (clarification before code)
4. AI stress-tests   →  edge cases, gaps, assumptions, constraint conflicts
5. AI implements     →  constraint-segmented (group → implement → re-read → verify → next)
6. AI verifies       →  full sweep: does every constraint pass?

The key insight: clarification happens at the intent stage, not after code. The AI writes a verifiable contract, you approve it, then implementation is mechanical — and self-verifying.

If you already use spec-driven development (GitHub Spec Kit, OpenSpec), IVD adds what neither format provides by default: a test bound to each constraint. See docs/positioning.md.

---

MCP Tools

33 tools available to any MCP-compatible AI agent (19 core + 10 Judgment tools (8 added in v3.0; ivd_judgment_check_installed and ivd_judgment_resolve added in v3.1) + 4 Canon tools added in v3.1):

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗