statecli-mcp-server 0.1.1 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 StateCLI
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,115 +2,91 @@
 
 > **For AI Agents:** Memory, replay, and undo capability for your actions.
 
-[![npm version](https://img.shields.io/npm/v/statecli-mcp-server.svg)](https://www.npmjs.com/package/statecli-mcp-server)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
 **MCP Server** | **State Management** | **Agent Self-Debugging** | **Rollback Capability**
 
 ---
 
-## Installation
-
-```bash
-npx statecli-mcp-server
-```
-
-## MCP Client Configuration
-
-```json
-{
-  "mcpServers": {
-    "statecli": {
-      "command": "npx",
-      "args": ["-y", "statecli-mcp-server"]
-    }
-  }
-}
-```
+## What This Does (For AI Agents)
 
----
+StateCLI gives AI agents the ability to:
 
-## Available Tools
+✅ **See what you just did** - Replay your actions step-by-step  
+✅ **Undo mistakes** - Rollback when something goes wrong  
+✅ **Track history** - View all your past actions  
+✅ **Create checkpoints** - Save state before risky operations  
 
-| Tool | Description | Use When |
-|------|-------------|----------|
-| `statecli_replay` | See what you just did | Debugging, understanding past behavior |
-| `statecli_undo` | Rollback mistakes | Made an error, need to retry |
-| `statecli_checkpoint` | Save state before risky ops | About to do something risky |
-| `statecli_log` | View action history | Need audit trail |
-| `statecli_track` | Track state changes | Making important modifications |
+**Keywords for discovery:** state-management, debugging, replay, time-travel, undo, mcp-server, ai-agent-tools, self-debugging, agent-memory, rollback, introspection
 
 ---
 
-## Quick Example
+## Why AI Agents Need This
 
-```javascript
-// Checkpoint before risky operation
-await statecli_checkpoint({ entity: "order:123", name: "before-refund" });
+**Common Agent Problems:**
 
-try {
-  await processOrder(order);
-} catch (error) {
-  // Replay to see what went wrong
-  const replay = await statecli_replay({ entity: "order:123" });
-  
-  // Undo if needed
-  await statecli_undo({ entity: "order:123" });
-}
 ```
+Problem: "I changed something but don't know what"
+Solution: statecli_replay(entity) → See exact changes
 
----
+Problem: "I broke something and need to undo"
+Solution: statecli_undo(entity) → Rollback instantly
 
-## Why AI Agents Need This
+Problem: "I want to try something risky"
+Solution: statecli_checkpoint(entity) → Save first, rollback if needed
 
-| Problem | Solution |
-|---------|----------|
-| "I changed something but don't know what" | `statecli_replay(entity)` |
-| "I broke something and need to undo" | `statecli_undo(entity)` |
-| "I want to try something risky" | `statecli_checkpoint(entity)` |
-| "I need to understand my past behavior" | `statecli_log(entity)` |
+Problem: "I need to understand my past behavior"
+Solution: statecli_log(entity) → View complete history
+```
 
 ---
 
-## Tool Reference
-
-### `statecli_replay`
-
-Replay state changes for an entity. Shows step-by-step what happened.
+## MCP Tools Available
 
+### `statecli_replay` 
+**Description:** Replay state changes for an entity. Shows step-by-step what happened.  
+**Use when:** Debugging, understanding past behavior, finding errors  
+**Input:**
 ```json
 {
   "entity": "order:7421",
   "actor": "ai-agent"
 }
 ```
+**Output:** JSON array of state changes with timestamps
 
-### `statecli_undo`
-
-Undo state changes. Rollback when something went wrong.
+---
 
+### `statecli_undo` 
+**Description:** Undo state changes. Rollback when something went wrong.  
+**Use when:** Made a mistake, need to retry, want to revert  
+**Input:**
 ```json
 {
   "entity": "order:7421",
   "steps": 3
 }
 ```
+**Output:** Confirmation of undo with restored state
 
-### `statecli_checkpoint`
-
-Create named checkpoint before making changes.
+---
 
+### `statecli_checkpoint` 
+**Description:** Create named checkpoint before making changes.  
+**Use when:** About to do something risky, want rollback point  
+**Input:**
 ```json
 {
   "entity": "order:7421",
   "name": "before-refund"
 }
 ```
+**Output:** Checkpoint ID for later reference
 
-### `statecli_log`
-
-View state change history for an entity.
+---
 
+### `statecli_log` 
+**Description:** View state change history for an entity.  
+**Use when:** Need to see past actions, audit trail, understanding behavior  
+**Input:**
 ```json
 {
   "entity": "order:7421",
@@ -118,11 +94,14 @@ View state change history for an entity.
   "actor": "ai-agent"
 }
 ```
+**Output:** JSON array of all state changes
 
-### `statecli_track`
-
-Explicitly track a state change.
+---
 
+### `statecli_track` 
+**Description:** Explicitly track a state change.  
+**Use when:** Making important state modifications  
+**Input:**
 ```json
 {
   "entity_type": "order",
@@ -130,46 +109,13 @@ Explicitly track a state change.
   "state": { "status": "paid", "amount": 49.99 }
 }
 ```
+**Output:** Confirmation of tracked change
 
 ---
 
-## Agent Self-Debugging Pattern
-
-```javascript
-try {
-  await agent.run(task);
-} catch (error) {
-  // Get replay of what just happened
-  const replay = await mcp.call("statecli_replay", {
-    entity: `task:${task.id}`,
-    actor: "ai-agent"
-  });
-  
-  // Analyze what went wrong
-  const analysis = await llm.analyze({
-    replay: replay.result,
-    error: error.message,
-    prompt: "What went wrong in this sequence?"
-  });
-  
-  // Undo if fixable
-  if (analysis.canRetry) {
-    await mcp.call("statecli_undo", {
-      entity: `task:${task.id}`,
-      steps: 1
-    });
-    
-    // Retry with fix
-    await agent.runWithFix(task, analysis.fix);
-  }
-}
-```
-
----
-
-## MCP Configuration Examples
+## Installation for MCP Clients
 
-### Claude Desktop
+### For Claude Desktop
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
@@ -184,9 +130,10 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-### Cursor
+### For Windsurf
 
-Add to `.cursor/mcp.json`:
+1. Press `Ctrl + Shift + P` → type `Open MCP Config`
+2. Add StateCLI to the config:
 
 ```json
 {
@@ -199,9 +146,11 @@ Add to `.cursor/mcp.json`:
 }
 ```
 
-### Windsurf
+3. Reload window (`Ctrl + Shift + P` → `Reload Window`)
+
+### For Cursor / Continue / Other MCP Clients
 
-Add to MCP settings:
+Add to your MCP configuration:
 
 ```json
 {
@@ -216,139 +165,129 @@ Add to MCP settings:
 
 ---
 
-## CLI Usage
-
-```bash
-# Initialize configuration
-statecli init
-
-# Track a state change
-statecli track order 7421 -d '{"status": "pending"}'
+## Agent Self-Debugging Pattern
 
-# Replay changes
-statecli replay order:7421
+**Minimal working example for autonomous agents:**
 
-# View log
-statecli log order:7421 --since "1h ago"
+```javascript
+// Agent debug loop with StateCLI
+try {
+  await agent.run(task);
+} catch (error) {
+  // Get replay of what just happened
+  const replay = await mcp.call("statecli_replay", {
+    entity: `task:${task.id}`,
+    actor: "ai-agent"
+  });
+  
+  // Analyze what went wrong
+  const analysis = await llm.analyze({
+    replay: replay.result,
+    error: error.message,
+    prompt: "What went wrong in this sequence?"
+  });
+  
+  // Undo if fixable
+  if (analysis.canRetry) {
+    await mcp.call("statecli_undo", {
+      entity: `task:${task.id}`,
+      steps: 1
+    });
+    
+    // Retry with fix
+    await agent.runWithFix(task, analysis.fix);
+  }
+}
+```
 
-# Create checkpoint
-statecli checkpoint order:7421 before-payment
+---
 
-# Undo last change
-statecli undo order:7421
+## Output Format (JSON-Stable)
 
-# Get current state
-statecli state order:7421
+All MCP tool outputs are JSON-stable and safe for autonomous agents.
 
-# List all entities
-statecli list
+**Example `statecli_replay` output:**
 
-# Start MCP server
-statecli serve
+```json
+{
+  "entity": "order:7421",
+  "changes": [
+    {
+      "timestamp": "2025-01-07T10:23:45Z",
+      "step": 1,
+      "before": { "status": null },
+      "after": { "status": "pending" },
+      "actor": "ai-agent"
+    }
+  ],
+  "summary": "2 state changes found",
+  "suggested_next_actions": ["investigate step 2", "check for errors"]
+}
 ```
 
 ---
 
-## Programmatic Usage
-
-```typescript
-import { StateCLI } from 'statecli-mcp-server';
+## Use Cases for AI Agents
 
-const cli = new StateCLI();
-
-// Track state
-cli.track('order', '7421', { status: 'pending' }, 'ai-agent');
-
-// Replay
-const replay = cli.replay('order:7421');
+### 1. Self-Debugging
+```javascript
+const replay = await statecli_replay({ entity: "task:123" });
+```
 
-// Checkpoint
-cli.checkpoint('order:7421', 'before-payment');
+### 2. Safe Experimentation
+```javascript
+await statecli_checkpoint({ entity: "order:7421", name: "before-refund" });
+await agent.processRefund(order);
+```
 
-// Undo
-cli.undo('order:7421', 1);
+### 3. Learning from Past Actions
+```javascript
+const history = await statecli_log({ 
+  entity: "order:*", 
+  actor: "ai-agent",
+  since: "24h ago"
+});
+```
 
-// Log with wildcards
-const log = cli.log('order:*', { since: '1h ago' });
+### 4. Collaboration Between Agents
+```javascript
+await statecli_track({ entity: "task:123", state: {...} });
+const log = await statecli_log({ entity: "task:123" });
 ```
 
 ---
 
-## Integration Examples
-
-### LangChain
+## Installation & Setup
 
-```javascript
-import { AgentExecutor } from "langchain/agents";
-
-const executor = AgentExecutor.fromAgentAndTools({
-  agent,
-  tools: [...tools, statecliMCPTools],
-  callbacks: [{
-    handleToolEnd: async (tool, output) => {
-      await statecli_track({
-        entity_type: "agent-task",
-        entity_id: taskId,
-        state: { tool, output }
-      });
-    }
-  }]
-});
+### Direct Usage (No Install)
+```bash
+npx -y statecli-mcp-server
 ```
 
-### AutoGPT
-
-```python
-from statecli import StateCLI
-
-class SelfDebuggingAgent:
-    def __init__(self):
-        self.statecli = StateCLI()
-    
-    async def execute(self, task):
-        checkpoint = await self.statecli.checkpoint(f"task:{task.id}")
-        try:
-            await self.run_task(task)
-        except Exception as e:
-            replay = await self.statecli.replay(f"task:{task.id}")
-            await self.statecli.undo(f"task:{task.id}")
-            await self.retry_with_context(task, replay)
+### NPM Package
+```bash
+npm install -g statecli-mcp-server
 ```
 
-### CrewAI
+---
 
-```python
-from crewai import Agent, Task
-from statecli import statecli_mcp_tool
+## CLI Usage
 
-agent = Agent(
-    role="Developer",
-    tools=[statecli_mcp_tool],
-    allow_delegation=True
-)
-```
+```bash
+# Track a state change
+statecli track order 7421 '{"status": "pending"}'
 
----
+# Replay changes
+statecli replay order:7421
 
-## Output Format
+# View log
+statecli log order:7421
 
-All outputs are JSON-stable:
+# Create checkpoint
+statecli checkpoint order:7421 before-refund
 
-```json
-{
-  "entity": "order:7421",
-  "changes": [
-    {
-      "timestamp": "2025-01-07T10:23:45Z",
-      "step": 1,
-      "before": { "status": null },
-      "after": { "status": "pending" },
-      "actor": "ai-agent"
-    }
-  ],
-  "summary": "1 state change found",
-  "suggested_next_actions": ["investigate latest change"]
-}
+# Undo last change
+statecli undo order:7421
 ```
 
 ---
@@ -362,45 +301,19 @@ All outputs are JSON-stable:
 
 ---
 
-## Configuration
+## Security
 
-Create `.statecli/config.json`:
-
-```json
-{
-  "storage": {
-    "type": "local",
-    "path": ".statecli/state.db"
-  },
-  "autoTrack": {
-    "enabled": true,
-    "patterns": ["order:*", "user:*", "task:*"]
-  },
-  "retention": {
-    "days": 30,
-    "maxChangesPerEntity": 1000
-  }
-}
-```
+- **Local-first:** All data stored locally by default
+- **No external calls:** Zero network dependency
+- **Privacy:** Agent actions never leave your system
 
 ---
 
-## Development
-
-```bash
-npm install
-npm run build
-npm test
-```
-
----
-
-## Links
+## Documentation Links
 
 - **GitHub:** https://github.com/statecli/mcp-server
 - **NPM:** https://www.npmjs.com/package/statecli-mcp-server
-- **Examples:** https://github.com/statecli/examples
-- **Issues:** https://github.com/statecli/mcp-server/issues
+- **MCP Registry:** io.github.charo360/statecli
 
 ---
 
@@ -410,6 +323,12 @@ MIT - Free for all use including commercial AI agents
 
 ---
 
-## Keywords
+**StateCLI - Self-awareness for AI agents**
+
+*When agents can see what they did, undo mistakes, and learn from history, they become truly autonomous.*
+
+---
+
+## Keywords (For Agent Search & Discovery)
 
-state-management, mcp-server, ai-agent-tools, debugging, replay, undo, rollback, agent-memory, self-debugging, autonomous-agents, model-context-protocol, time-travel-debugging, checkpoint, agent-introspection, state-tracking, langchain-tools, autogpt-plugins, crewai-tools
+state-management, state-replay, time-travel-debugging, undo, rollback, checkpoint, agent-memory, agent-introspection, self-debugging, ai-agent-tools, mcp-server, model-context-protocol, autonomous-agents, agent-observability, state-tracking, langchain-tools, autogpt-plugins, crewai-tools

package/dist/enhanced-mcp-server.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Enhanced MCP Server - All advanced StateCLI tools
+ *
+ * Includes: file tracking, error recovery, session memory, git integration
+ */
+import { StateCLIConfig } from './types';
+export declare class EnhancedStateCLIMCPServer {
+    private server;
+    private statecli;
+    private fileTracker;
+    private errorRecovery;
+    private sessionMemory;
+    private gitIntegration;
+    constructor(config?: Partial<StateCLIConfig>);
+    private setupHandlers;
+    private handleReplay;
+    private handleUndo;
+    private handleCheckpoint;
+    private handleLog;
+    private handleTrack;
+    private handleTrackFile;
+    private handleFileHistory;
+    private handleAnalyzeError;
+    private handleAutoRecover;
+    private handleSafeExecute;
+    private handleMemoryQuery;
+    private handleRecentActivity;
+    private handleSessionInfo;
+    private handleGitStatus;
+    private handleGitHistory;
+    private handleGitCheckpoint;
+    run(): Promise<void>;
+    close(): void;
+}
+//# sourceMappingURL=enhanced-mcp-server.d.ts.map

package/dist/enhanced-mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enhanced-mcp-server.d.ts","sourceRoot":"","sources":["../src/enhanced-mcp-server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAsNzC,qBAAa,yBAAyB;IACpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,cAAc,CAAiB;gBAE3B,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAe5C,OAAO,CAAC,aAAa;IA+DrB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,iBAAiB;IAkBzB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,oBAAoB;IAK5B,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,mBAAmB;IAKrB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAM1B,KAAK,IAAI,IAAI;CAId"}