# mnehmos.synch.mcp

[![npm version](https://img.shields.io/npm/v/mnehmos-synch-mcp.svg)](https://www.npmjs.com/package/mnehmos-synch-mcp)
[![CI](https://github.com/Mnehmos/mnehmos.synch.mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Mnehmos/mnehmos.synch.mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Global Memory Bank for AI Agents**

An MCP server that provides persistent context synchronization for AI agents across sessions and projects.

## Features

- **Active Context** - Get/set current working state per project
- **Filing Cabinet** - Index files with summaries and metadata for fast retrieval
- **Memory Search** - Search across all indexed content
- **Spatial Map** - "PC as Rooms" folder navigation metaphor
- **Bug Tracking** - Log and resolve bugs for agent workflows
- **Lock Management** - Concurrent agent access coordination
- **Context Events** - Agent-to-agent handoff protocol

## Installation

**Prerequisites:** Node.js 18.0.0 or higher

### From NPM (Recommended)

```bash
npm install -g mnehmos-synch-mcp
```

### From Source

```bash
git clone https://github.com/Mnehmos/mnehmos.synch.mcp.git
cd mnehmos.synch.mcp
npm install
npm run build
```

## Configuration

Add to your MCP client config (Claude Desktop, Cline, etc.):

```json
{
  "mcpServers": {
    "mnehmos-synch-mcp": {
      "command": "npx",
      "args": ["mnehmos-synch-mcp"]
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "mnehmos-synch-mcp": {
      "command": "mnehmos-synch-mcp"
    }
  }
}
```

## Tools

### Context Management

| Tool | Description |
|------|-------------|
| `get_active_context` | Get current summary/focus for a project |
| `set_active_context` | Update active context state |
| `list_projects` | List all projects in memory bank |

### Filing Cabinet

| Tool | Description |
|------|-------------|
| `file_to_cabinet` | Index a file with summary and metadata |
| `get_from_cabinet` | Retrieve indexed file info |
| `search_memory` | Search across all indexed content |

### Spatial Map

| Tool | Description |
|------|-------------|
| `get_spatial_map` | Get folder structure as "rooms" |
| `add_room` | Add folder to spatial map |
| `link_rooms` | Connect two folders |

### Bug Tracking

| Tool | Description |
|------|-------------|
| `log_bug` | Log a bug for later fixing |
| `get_bugs` | Get bugs by project/status |
| `resolve_bug` | Mark bug as resolved |

### Concurrent Access

| Tool | Description |
|------|-------------|
| `acquire_lock` | Lock a resource for exclusive access |
| `release_lock` | Release a held lock |
| `get_lock_status` | Check lock state |

### Agent Coordination

| Tool | Description |
|------|-------------|
| `emit_context_event` | Emit handoff/checkpoint/error events |
| `get_context_events` | Get recent context events |

### Server Configuration

| Tool | Description |
|------|-------------|
| `configure_server` | First-run setup for server location |
| `get_server_info` | Get server configuration |

## Usage

```typescript
// Set active context for a project
await client.callTool("set_active_context", {
  project_id: "my-app",
  summary: "Working on authentication module",
  focus: "src/auth/login.ts"
});

// Index a file
await client.callTool("file_to_cabinet", {
  project_id: "my-app",
  file_path: "src/auth/login.ts",
  summary: "Login handler with JWT validation",
  key_exports: ["login", "validateToken"]
});

// Search memory
await client.callTool("search_memory", {
  query: "authentication",
  project_id: "my-app"
});

// Emit handoff event
await client.callTool("emit_context_event", {
  project_id: "my-app",
  agent_id: "agent-1",
  event_type: "handoff",
  summary: "Completed auth module, ready for testing"
});
```

## Data Storage

Data is stored locally in SQLite with Markdown file fallbacks:

| Platform | Location |
|----------|----------|
| **Windows** | `%USERPROFILE%\.agent-synch\` |
| **macOS/Linux** | `~/.agent-synch/` |

Storage includes:
- `agent_synch.db` - SQLite database
- `projects/{id}/` - Per-project markdown files
- `.locks/` - Lock files for crash recovery

## Development

```bash
# Install dependencies
npm install

# Development mode with watch
npm run dev

# Run tests
npm test

# Build for production
npm run build
```

## License

MIT

## Author

[Mnehmos](https://github.com/Mnehmos)

## Links

- [NPM Package](https://www.npmjs.com/package/mnehmos-synch-mcp)
- [GitHub Repository](https://github.com/Mnehmos/mnehmos.synch.mcp)
- [Changelog](https://github.com/Mnehmos/mnehmos.synch.mcp/blob/master/CHANGELOG.md)