MCP Tool Factory

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

Sacred Primitive

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

Using with Claude Desktop

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

Conversational Interface Examples

Identity Query

Hypothetical Evaluation (NEW in M2)

Approval Flow

Architecture

Project Structure

Development Phases

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

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