# DPR MCP AI Document Collaboration Platform

This project is a local, Git-backed document collaboration platform where humans
and AI agents can work on shared documents safely.

It combines:

- Model Context Protocol server
- real MCP stdio client
- React dashboard
- LangGraph-based agents
- Git-backed versioning
- isolated workspaces
- Change Requests
- human review and merge
- conflict detection
- conflict-resolution proposals
- provenance tracking

The core idea:

```text
AI agents can write and review documents, but they cannot silently overwrite main.
Every edit becomes a versioned, reviewable, traceable Change Request.
```

## Why This Project Exists

Normal AI document editing is risky because an agent may directly overwrite a
file, lose history, mix multiple users' edits, or make it unclear who changed
what and why.

This project solves that by placing AI agents behind a controlled collaboration
protocol:

```text
Agent -> MCP Client -> MCP Server -> Controlled Tools -> Git + SQLite
```

The agent does not directly mutate the canonical document repository. It creates
an isolated workspace, edits files there, opens a Change Request, and waits for
human review.

## Architecture

Full project architecture:

![Project architecture](docs/project-architecture.png)

Phase 2 agent architecture:

![Phase 2 agent architecture](docs/phase2-agent-architecture.png)

High-level flow:

```text
React Dashboard / External MCP Client
        |
        v
Dashboard API
        |
        v
LangGraph Agents
        |
        v
DPRMCPClient
        |
        v
MCP stdio
        |
        v
DPR MCP Server
        |
        v
MCP Tools
        |
        v
DPR Services
        |
        v
Git Repositories + Isolated Workspaces + SQLite Metadata
```

## Main Components

### MCP Server

The MCP server is the controlled backend interface. It exposes safe tools for
document collaboration.

Entry point:

```text
src/dpr_mcp/server.py
```

Important tools:

- `create_project`
- `create_workspace`
- `read_project_file`
- `read_change_file`
- `create_file`
- `edit_file`
- `create_change`
- `review_change`
- `approve_change`
- `merge_change`
- `get_diff`
- `get_file_patch`
- `get_conflicts`
- `propose_conflict_resolution`
- `apply_conflict_resolution`
- `rollback_change`
- `get_provenance`

Run directly:

```cmd
python -m dpr_mcp.server
```

The server speaks MCP over stdio. Usually a client communicates with it; you do
not manually type into the process.

### Real MCP Client

The reusable MCP client lives here:

```text
src/dpr_mcp/mcp/client.py
```

It starts/connects to the DPR MCP server over stdio and calls tools by name.
This is the same idea used by external MCP clients such as Claude Code.

Run the real client demo:

```cmd
python examples\real_mcp_client.py
```

Expected output:

```text
Connected to DPR MCP server. 35 tools available.
Project: client-demo
Workspace: ws-...
Change request: CR-...
Open changes: 1
```

### React Dashboard

The dashboard is the human-facing UI.

It lets a user:

- choose the local DPR root folder
- create projects
- view documents
- run agents
- inspect Change Requests
- review diffs
- merge approved changes
- inspect conflicts
- view history and provenance

Backend:

```text
src/dpr_mcp/dashboard.py
```

Frontend:

```text
frontend/
```

### LangGraph Agents

The agent workflow layer lives here:

```text
src/dpr_mcp/agents/workflows.py
```

The live dashboard agent actions create a real `DPRMCPClient`, connect to the
MCP server over stdio, and call MCP tools. So the agent path is now:

```text
Dashboard -> LangGraph Agent -> DPRMCPClient -> MCP Server -> MCP Tools
```

Current agents:

- Draft Agent
- Reviewer Agent
- Compliance Agent
- Conflict Resolver Agent

LLM integration lives here:

```text
src/dpr_mcp/agents/llm.py
```

Supported modes:

- Groq
- OpenAI
- fallback mode if no key is configured

## Agent Workflow

### Draft Agent

The Draft Agent creates or improves a document.

Example prompt:

```text
Write a detailed report about smart waste segregation for a college campus.
```

Internal flow:

```text
Dashboard
-> LangGraph Draft Agent
-> DPRMCPClient
-> MCP server
-> list_files
-> read_project_file if the file exists
-> create_workspace
-> create_file or edit_file
-> create_change
```

Result:

```text
A new Change Request is created.
The file is not directly merged into main.
```

### Reviewer Agent

The Reviewer Agent checks:

- clarity
- structure
- completeness
- technical usefulness
- whether the change matches the user's intent

Internal flow:

```text
Reviewer Agent
-> DPRMCPClient
-> get_change
-> get_diff
-> get_file_patch
-> review_change
```

Result:

```text
A review comment is added to the Change Request.
```

The Reviewer Agent does not replace human approval. It provides feedback before
a human decides whether to merge.

### Compliance Agent

The Compliance Agent checks whether a change is safe and policy-friendly.

It looks for:

- unsupported file types
- secrets or credentials
- placeholder text
- invented evidence
- unsafe claims
- missing report sections

Internal flow:

```text
Compliance Agent
-> DPRMCPClient
-> get_change
-> get_diff
-> get_file_patch
-> review_change
```

Result:

```text
The Change Request receives a compliance review.
If there is a blocking issue, the review requests changes.
```

### Conflict Resolver Agent

The Conflict Resolver Agent is used when Git detects a real merge conflict.

Internal flow:

```text
Resolver Agent
-> DPRMCPClient
-> get_change
-> get_conflicts
-> create_workspace
-> read_project_file
-> read_change_file
-> edit_file
-> propose_conflict_resolution
```

Result:

```text
A new resolution Change Request is created.
The human still reviews and merges the resolution.
```

The resolver does not bypass review. It only proposes a fix.

## How a Real Conflict Happens

A conflict happens when two changes edit the same part of the same file from the
same old base.

Example:

```text
main has report.md
```

Then:

```text
Agent A creates CR-1 editing report.md
Agent B creates CR-2 editing the same paragraph in report.md
Human merges CR-1 first
Human tries to merge CR-2
Git detects that CR-2 was based on old main and touched the same lines
CR-2 becomes conflicted
```

Then:

```text
Conflict Resolver Agent reads current main and incoming CR-2
Resolver writes a combined version in a new workspace
Resolver opens a resolution CR
Human reviews and merges the resolution CR
```

This is a real Git conflict flow, not a fake UI-only conflict.

## Where Files Are Created

The dashboard asks for a root folder.

If the root is:

```text
C:\Users\janan\dpr-mcp\data
```

then the system uses:

```text
data\projects      -> canonical Git repositories
data\workspaces    -> isolated Git worktrees
data\dpr_mcp.db    -> SQLite metadata database
```

Important:

```text
Documents are local files inside Git-backed project repositories.
Workspaces are temporary isolated edit areas.
SQLite stores metadata such as workspaces, changes, reviews, conflicts, and roles.
```

## Why Git Is Used

Git handles:

- commits
- branches
- worktrees
- diffs
- mergeability checks
- merge conflicts
- merge history
- rollback through forward commits

The project does not reinvent version control. It uses Git as the source of
truth and adds collaboration workflow above it.

## Why SQLite Is Used

Git is good for file history, but it does not naturally store collaboration
metadata such as:

- Change Request status
- reviewer comments
- approvals
- conflict-resolution records
- workspace ownership
- role bindings
- event logs

That metadata is stored in SQLite.

## Human Governance

The system is intentionally human-in-the-loop.

Agents can:

- draft documents
- review changes
- check compliance
- propose conflict resolutions

Humans control:

- final approval
- merge
- rollback
- project access/root selection

This is important because the project is about safe AI-assisted collaboration,
not uncontrolled autonomous editing.

## Security Model

File operations are restricted to the configured repository and workspace roots.

The file security layer rejects:

- absolute paths
- path traversal
- symlink escapes
- null bytes
- control characters
- sensitive filenames such as `.env`, private keys, and credentials

Relevant files:

```text
src/dpr_mcp/files/security.py
src/dpr_mcp/files/service.py
tests/security/
```

## Setup

From CMD on Windows:

```cmd
cd /d C:\Users\janan\dpr-mcp
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
cd frontend
npm install
cd ..
```

If the environment already exists:

```cmd
cd /d C:\Users\janan\dpr-mcp
.venv\Scripts\activate
```

## Environment Variables

Create a `.env` file in the project root if using real LLMs.

For Groq:

```env
DPR_LLM_PROVIDER=groq
GROQ_API_KEY=your_key_here
DPR_LLM_MODEL=llama-3.3-70b-versatile
```

For OpenAI:

```env
DPR_LLM_PROVIDER=openai
OPENAI_API_KEY=your_key_here
DPR_LLM_MODEL=gpt-5
```

If no key is configured, the agents still run in fallback mode, but the content
will be basic.

## Run the Dashboard

Backend:

```cmd
cd /d C:\Users\janan\dpr-mcp
.venv\Scripts\activate
python -m dotenv run -- python -m dpr_mcp.dashboard --host 127.0.0.1 --port 8787 --root data
```

Frontend:

```cmd
cd /d C:\Users\janan\dpr-mcp\frontend
npm run dev
```

Open the Vite URL shown in the terminal, usually:

```text
http://127.0.0.1:5173
```

The dashboard backend API runs at:

```text
http://127.0.0.1:8787
```

## Run the MCP Server Directly

```cmd
cd /d C:\Users\janan\dpr-mcp
.venv\Scripts\activate
python -m dpr_mcp.server
```

This starts the MCP server over stdio.

## Run the Real MCP Client Demo

```cmd
cd /d C:\Users\janan\dpr-mcp
.venv\Scripts\activate
python examples\real_mcp_client.py
```

This proves:

```text
Python client
-> MCP stdio server
-> MCP tools
-> project/workspace/file/change created
```



## Repository Map

```text
src/dpr_mcp/server.py              MCP server entry point
src/dpr_mcp/dashboard.py           local dashboard HTTP API
src/dpr_mcp/mcp/tools.py           MCP tool definitions
src/dpr_mcp/mcp/client.py          real MCP stdio client
src/dpr_mcp/mcp/gateway.py         in-process MCP-shaped gateway
src/dpr_mcp/agents/workflows.py    LangGraph agent workflows
src/dpr_mcp/agents/llm.py          Groq/OpenAI/fallback generation
src/dpr_mcp/projects/              project repository management
src/dpr_mcp/workspace/             isolated worktree management
src/dpr_mcp/collaboration/         changes, reviews, approvals, conflicts
src/dpr_mcp/files/                 safe local file access
src/dpr_mcp/git/                   Git CLI wrapper
src/dpr_mcp/persistence/           SQLite models and repositories
src/dpr_mcp/provenance/            provenance reconstruction
frontend/                          React dashboard
examples/                          runnable MCP and conflict demos
tests/                             unit, integration, security, MCP tests
docs/                              architecture and technical docs
```


## Current Status

Implemented:

- MCP server
- real MCP stdio client
- React dashboard
- LangGraph agents
- LLM integration
- local Git project repositories
- isolated workspaces
- Change Requests
- reviews
- compliance checks
- merge flow
- conflict detection
- conflict-resolution proposals
- rollback
- provenance
- architecture diagrams
- tests