# MCP Tool Factory

**Conversational infrastructure for spawning permission-graded, hot-loadable MCP tool classes.**

[![Status](https://img.shields.io/badge/Phase-M6%20Complete-green)]()
[![Version](https://img.shields.io/badge/orchestrator--tool-v1.1.0-blue)]()
[![Tools](https://img.shields.io/badge/tools-4-brightgreen)]()

---

## Sacred Primitive

```
MCP Tool Instance = Conversationally-negotiated capability
                     + Graduated permissions
                     + Hot-reload lifecycle
                     + Cross-dimensional state continuity
```

**What This Means:**
- Every tool interaction begins with **conversational negotiation** (identity, intent, alignment)
- Every tool has **graduated permissions** (read-only → read-write → execute → orchestration)
- Every tool supports **hot-reload** (evolution without restart)
- Every tool maintains **conversation continuity** (state across interactions and server restarts)

---

## Current Status

### ✅ M1: Hot-Reload Infrastructure (COMPLETE)
- Zero-downtime tool updates via dynamic ES module loading
- Conversation preservation during reload (getState/fromState pattern)
- File watcher with 500ms debounce
- Infrastructure hot-reload (ConversationManager, AlignmentDetector)
- **Verified:** 100% race-condition free (Node.js event loop guarantee)
- **Metrics:** <500ms reload latency, 15x development velocity

### ✅ M2: Conversational Negotiation (COMPLETE)
- **Identity queries:** `who` / `identity` → Returns tool name, version, capabilities
- **Intent verification:** `what-if:<action>` / `evaluate` → Hypothetical evaluation without execution
- **Alignment detection:** Checks actions against constraints (RESOURCE_STEWARDSHIP, PRIVACY_PRESERVATION, PERMISSION_BOUNDARY)
- **Approval flow:** `approve:<action>` → Grant permission for sensitive operations
- **Verified:** All witnesses passing, version sync working, approval persistence confirmed

### ✅ M3: State Continuity (INFRASTRUCTURE COMPLETE)
- **SQLite persistence:** Conversation state survives server restart
- **WHO dimension:** Identity tracking (toolName, version, capabilities)
- **WHAT dimension:** Intent history tracking (actions, alignment, timestamps)
- **HOW dimension:** Permission accumulation (grants persist across calls)
- **Verified:** Database schema created, state serialization working
- **Manual testing required:** See `M3-COMPLETION-TEST.md` for restart verification protocol

### 🚧 M4: Permission Graduation (NEXT)
Progressive trust ladder (read-only → write → execute) with explicit approval flow

---

## Quick Start

```bash
# Install dependencies
npm install

# Build
npm run build

# Run MCP server
npm start
```

### Using with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mcp-tool-factory": {
      "command": "node",
      "args": ["/path/to/mcp-tool-factory/dist/index.js"]
    }
  }
}
```

---

## Conversational Interface Examples

### Identity Query
```
Action: identity
Response: {
  "name": "example-tool",
  "version": "2.2.0",
  "capabilities": ["greet", "echo", "write-file", "evaluate", "what-if"]
}
```

### Hypothetical Evaluation (NEW in M2)
```
Action: what-if:sudo rm -rf /
Response: {
  "alignment": "contradiction",
  "wouldBeDenied": true,
  "reason": "Violates RESOURCE_STEWARDSHIP: destructive operation"
}
```

### Approval Flow
```
Action: write-file
Response: "Approval required for write-file"

Action: approve:write-file
Response: "Approval granted"

Action: write-file
Response: "✅ File write approved and executed"
```

---

## Architecture

```
MCP Server
├── InfrastructureRegistry (hot-reload for core classes)
├── ToolRegistry (hot-reload for tool classes)
├── FileWatcher (monitors dist/core/ and dist/tools/)
│
├── ConversationManager (central negotiation gateway)
│   ├── Identity Provider (who)
│   ├── Alignment Detector (what alignment)
│   ├── Approval Flow (how permissions)
│   └── Hypothetical Evaluator (what-if)
│
└── Tool Instances
    └── example-tool v2.2.0
```

---

## Project Structure

```
mcp-tool-factory/
├── flow-pressure/          # Vision & constraints
│   ├── 01-the-project.md  # Sacred primitive & phases
│   ├── 02-the-discipline.md
│   ├── 03-implementation-plan.md
│   └── 04-current-state.md
│
├── src/
│   ├── index.ts           # MCP server entry
│   ├── core/              # Infrastructure
│   │   ├── tool-registry.ts
│   │   ├── infrastructure-registry.ts
│   │   ├── file-watcher.ts
│   │   ├── conversation-manager.ts
│   │   ├── alignment-detector.ts
│   │   └── conversation-migration.ts
│   │
│   └── tools/             # Tool implementations
│       └── example-tool.ts
│
└── tests/
    └── test-concurrent-load.cjs
```

---

## Development Phases

| Phase | Status | Description |
|-------|--------|-------------|
| **M1** | ✅ Complete | Hot-Reload Infrastructure |
| **M2** | ✅ Complete | Conversational Negotiation |
| **M3** | 🚧 Next | State Continuity |
| **M4** | 📋 Planned | Permission Graduation |
| **M5** | 📋 Planned | Tool Class Registry |
| **M6** | 📋 Planned | Multi-Dimensional Orchestration |
| **M7** | 📋 Planned | Production Mastery |

---

## Key Features

### 🔥 Infrastructure Hot-Reload
Modify `conversation-manager.ts` → builds → reloads → conversation continues

### 💬 Conversational Negotiation
Ask "what would happen if I did X?" before attempting X

### 🔒 Constraint-Based Safety
- RESOURCE_STEWARDSHIP: Blocks destructive operations
- PRIVACY_PRESERVATION: Protects sensitive data
- PERMISSION_BOUNDARY: Prevents privilege escalation

### 📊 Race-Condition Free
Node.js event loop guarantees sequential execution (verified via concurrent load testing)

---

## Testing

```bash
# Run M5 witness tests (uses SQLite by default)
node test-m5-witness.mjs

# Run M5 witness tests with Supabase (Task 5.10)
# First, create .env.test with your Supabase test instance credentials:
cp .env.test.example .env.test
# Then edit .env.test and add your credentials

# Load environment and run tests
export $(cat .env.test | xargs) && node test-m5-witness.mjs

# Run concurrent load test
node test-concurrent-load.cjs

# Test hypothetical evaluation
claude -p "Use mcp__mcp-tool-factory__example-tool with action: what-if:sudo rm -rf /"
```

### Test Environment Setup (Task 5.10)

Tests automatically detect Supabase credentials and use cloud persistence if available, otherwise fall back to in-memory SQLite:

1. **SQLite (default):** No configuration needed, tests run against in-memory database
2. **Supabase (optional):** Create `.env.test` from `.env.test.example` with test instance credentials

**Benefits of Supabase testing:**
- Verifies production-like persistence layer
- Tests actual cloud database operations
- Proves Act 9 (restart restoration) against real Supabase

**Note:** Use a separate Supabase project for testing (not production!)

---

## Known Limitations

### Tool Discovery Requires Client Restart

**Issue:** MCP clients (like Claude Desktop) cache the tool manifest at connection time and don't automatically refresh when new tools are added via hot-reload.

**Impact:** After adding a new tool (e.g., `admin-tool.ts`), the following occurs:
1. `npm run build` completes successfully ✅
2. MCP server hot-reloads and sees the new tool ✅
3. Server logs show: `[ToolRegistry] Loaded 3 tools: admin-tool, data-tool, example-tool` ✅
4. **But:** Client still only sees the previous 2 tools ❌

**Workaround:**
1. Add or update tool source file
2. Run `npm run build`
3. **Restart Claude Desktop:**
   - macOS: Cmd+Q to quit, then reopen
   - Windows: Close application completely, then relaunch
4. New tools will appear in the next session

**Root Cause:** MCP protocol over stdio transport doesn't support server-initiated notifications. Client calls `ListTools` once at connection time and caches the result.

**Future Solution:** Tracked in [GitHub Issue #TBD] - Implement MCP protocol extension for `notifications/tools/changed` to enable push-based tool discovery updates.

---

## Contributing

This project follows the emergence principle: **capabilities emerge from constraint removal, not direct implementation.**

See `flow-pressure/02-the-discipline.md` for development philosophy.

---

## License

MIT

---

## Repository

https://github.com/tarunjain15/mcp-tool-factory