Metadata-Version: 2.4
Name: remembril-mcp
Version: 0.2.0
Summary: MCP server for Remembril - change impact tracking, ripple effects, Graphify bridge, and autonomous coding loop
Project-URL: Homepage, https://www.remembril.com
Project-URL: Documentation, https://www.remembril.com/api-docs/mcp-tools.html
Project-URL: Repository, https://github.com/remembril/remembril-mcp
Project-URL: Changelog, https://github.com/remembril/remembril-mcp/blob/main/CHANGELOG.md
Author-email: Remembril <support@remembril.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,change-tracking,impact-analysis,mcp,remembril
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: click>=8.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: starlette>=0.37.0; extra == 'dev'
Requires-Dist: uvicorn>=0.27.0; extra == 'dev'
Provides-Extra: http
Requires-Dist: starlette>=0.37.0; extra == 'http'
Requires-Dist: uvicorn>=0.27.0; extra == 'http'
Description-Content-Type: text/markdown

# Remembril MCP Server

MCP (Model Context Protocol) server for [Remembril](https://www.remembril.com) — change impact tracking, autonomous coding loops, Graphify knowledge-graph bridge, and documentation automation for AI coding assistants.

**57 tools** across 9 categories, exposed over stdio and streamable HTTP. Three output tiers: MCP Apps widgets (Claude Desktop / ChatGPT), A2UI declarative JSON (Google Gemini), and plain-text markdown (Claude Code CLI and any MCP host).

## What is Remembril?

Remembril tracks changes through your entire documentation hierarchy: Requirements, PRFAQ, HLD, LLD, Tests, Compliance, and Runbooks. When something changes, ripple effects propagate automatically. The autonomous coding loop can then implement those changes via Claude Code with an AI review committee as quality gate. The Graphify bridge overlays code-level symbols from [safishamsi/graphify](https://github.com/safishamsi/graphify) into the same knowledge graph, so requirements and actual code live in one connected graph.

## Installation

```bash
pip install remembril-mcp

# Optional: include the HTTP transport for Claude Desktop / ChatGPT / Gemini
pip install 'remembril-mcp[http]'
```

## Quick Start

### 1. Setup for Claude Code

Run the setup script (if you have the repo):
```bash
cd mcp-server
./setup-claude-code.sh
```

Or configure manually in `~/.claude/settings.json`:
```json
{
  "mcpServers": {
    "remembril": {
      "command": "remembril-mcp",
      "args": ["serve"],
      "env": {
        "REMEMBRIL_URL": "http://localhost:7070",
        "REMEMBRIL_TOKEN": "your-token-here"
      }
    }
  }
}
```

### 2. Authenticate

```bash
remembril-mcp login --url http://localhost:7070
```

### 3. Create a project and configure it

From Claude Code, just say:

> "Create a Remembril project for this repo and set up the coding loop"

The AI will call `remembril_project_create` and `remembril_project_configure` with your repo path, test command, etc.

Or via CLI:
```bash
remembril-mcp projects                    # List projects
remembril-mcp set-project YOUR_PROJECT_ID # Set default
```

## Available MCP Tools

### Project Management

| Tool | Description |
|------|-------------|
| `remembril_projects` | List all projects |
| `remembril_project_create` | Create a new project |
| `remembril_project_configure` | Configure repo path, test command, agent review, coding loop |
| `remembril_project_settings` | View current pipeline settings |

### Issues & Ripples

| Tool | Description |
|------|-------------|
| `remembril_issue_create` | Create a new issue |
| `remembril_issue_create_smart` | Create issue with auto-severity |
| `remembril_issue_list` | List issues with filters |
| `remembril_ripples_generate` | Generate ripple effects for an issue |
| `remembril_ripples_queue` | Get pending ripples for review |
| `remembril_ripple_approve` | Approve a ripple |
| `remembril_ripple_reject` | Reject a ripple with reason |
| `remembril_ripple_update` | Modify a ripple's changes |
| `remembril_ripple_apply` | Apply an approved ripple to its document |
| `remembril_ripple_diff` | View the diff a ripple would produce |
| `remembril_ripple_blind_review` | Get ripples with AI reasoning hidden (blind validation) |

### Pipeline & Documents

| Tool | Description |
|------|-------------|
| `remembril_pipeline_run` | Run the full auto-pipeline (issues -> ripples -> docs) |
| `remembril_pipeline_status` | Check pending work for a project |
| `remembril_pipeline_generate_docs` | Export documents to markdown |
| `remembril_docs` | List project documents |
| `remembril_doc_read` | Read a specific document |
| `remembril_doc_traceability` | View cross-document traceability matrix |

### Autonomous Coding Loop

| Tool | Description |
|------|-------------|
| `remembril_loop_start` | Start a coding loop (Issue -> Code -> Test -> Review -> Merge) |
| `remembril_loop_status` | Check loop progress, waves, and droplets |
| `remembril_loop_stop` | Stop a running loop |

### Pull-Based Work Loop (v0.2.0)

Agents pull atomic droplets over MCP instead of being driven by a subprocess. Respects `depends_on_id` chains — blocked droplets stay hidden until their dependency completes.

| Tool | Description |
|------|-------------|
| `remembril_loop_next_task` | Get the next available droplet for the calling agent |
| `remembril_loop_claim_task` | Claim a droplet so no other worker picks it up |
| `remembril_loop_checkpoint` | Periodic progress update while working |
| `remembril_loop_complete_task` | Mark a droplet complete, unblocks downstream |

### Graphify Bridge (v0.2.0)

Integrates with [safishamsi/graphify](https://github.com/safishamsi/graphify) (PyPI `graphifyy`) — a tree-sitter + Leiden knowledge graph builder. Diffs between snapshots become issue-shaped ripple payloads for the change-impact pipeline.

| Tool | Description |
|------|-------------|
| `remembril_graphify_import` | Parse a Graphify `graph.json` and map it into Remembril's knowledge graph |
| `remembril_graphify_diff` | Diff two snapshots, emit issue-shaped ripple payloads for added/removed nodes and edges |
| `remembril_graphify_sync` | Rebuild the Graphify graph for a project dir (requires `graphifyy` on the backend) |

### Agent Review (Auror Committee)

| Tool | Description |
|------|-------------|
| `remembril_review_run` | Run an AI review committee on content |
| `remembril_review_status` | Check review status |
| `remembril_review_list` | List reviews for a project |
| `remembril_review_approve_ripples` | Approve ripples from a review |
| `remembril_debate_create` | Start a debate between agents |
| `remembril_debate_status` | Check debate progress |
| `remembril_watcher_alerts` | View anomaly alerts from the watcher |
| `remembril_alert_handle` | Handle a watcher alert |
| `remembril_personas_list` | List available review personas |

### Code Intelligence

| Tool | Description |
|------|-------------|
| `remembril_scan` | Index a codebase for symbol tracking |
| `remembril_impact` | Analyze file change impact |
| `remembril_trace` | Trace requirement to code |
| `remembril_symbols` | Search code symbols |

### Orchestration

| Tool | Description |
|------|-------------|
| `remembril_orchestrate_status` | Check pending work |
| `remembril_orchestrate_start` | Start an orchestration session |
| `remembril_orchestrate_next` | Get next task in session |
| `remembril_orchestrate_complete` | Complete a task |
| `remembril_orchestrate_sessions` | List sessions |
| `remembril_orchestrate_generate_all` | Generate all pending ripples |

## CLI Commands

```bash
# Authentication
remembril-mcp login              # Login via browser
remembril-mcp login -t TOKEN     # Login with token
remembril-mcp logout             # Remove credentials
remembril-mcp status             # Check connection

# Projects
remembril-mcp projects           # List projects
remembril-mcp set-project ID     # Set default project

# Server
remembril-mcp serve              # Start MCP server (stdio)

# Issues
remembril-mcp issue "Title" -d "Description"
remembril-mcp issue "Title" --auto-severity

# Ripple Workflow
remembril-mcp run 123            # Generate ripples for issue
remembril-mcp review 123         # Interactive review
remembril-mcp review 123 --blind # Blind validation
remembril-mcp resume 123         # Resume reviewing
remembril-mcp logs               # View history
```

## Typical Workflow

```
1. Create project           -> remembril_project_create
2. Configure repo + tests   -> remembril_project_configure
3. Create issues             -> remembril_issue_create
4. Run pipeline              -> remembril_pipeline_run
   (generates ripples across Requirements, PRFAQ, HLD, LLD, Tests, Compliance, Runbook)
5. Start coding loop         -> remembril_loop_start
   (Claude Code implements changes, tests run, Auror committee reviews, auto-merge)
6. Check progress            -> remembril_loop_status
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `REMEMBRIL_URL` | API URL (default: https://www.remembril.com) |
| `REMEMBRIL_TOKEN` | Authentication token |
| `REMEMBRIL_PROJECT_ID` | Default project ID |

## HTTP Transport (v0.2.0)

Run the server over streamable HTTP instead of stdio — required for Claude Desktop, ChatGPT, and Google Gemini hosts that don't support stdio subprocesses.

```bash
pip install 'remembril-mcp[http]'
remembril-mcp serve --http --port 8080
```

Exposes:

| Path | Purpose |
|------|---------|
| `POST /mcp` | StreamableHTTP transport (stateless sessions per request) |
| `GET /sse`, `POST /messages/` | Server-Sent Events transport (legacy) |
| `GET /health` | Health check |

### Claude Desktop / ChatGPT config

```json
{
  "mcpServers": {
    "remembril": {
      "type": "http",
      "url": "https://mcp.remembril.com/mcp"
    }
  }
}
```

## Output Tiers

Every tool supports three output tiers so any MCP host gets the best available rendering:

1. **MCP Apps** — HTML widget bundles (Claude Desktop, ChatGPT). Five widgets: `ripple-review`, `traceability`, `pipeline-dashboard`, `design-preview`, `agent-review`.
2. **A2UI** — declarative JSON (Google Gemini). Includes Cards, DataTable, ProgressBar, DesignPreview, AgentReview, WatcherAlerts.
3. **Text** — markdown fallback (Claude Code CLI, any MCP host).

## Configuration

Credentials stored in `~/.remembril/config.json` (600 permissions).

## License

MIT
