procedure-memory-mcp-server/README.md

Procedure memory management system with MCP integration using Zep

# Procedure Memory MCP Server

A Model Context Protocol (MCP) server implementation for searching operational procedures and knowledge using Zep memory service. This server provides tools for searching and retrieving operational documentation, procedures, workflows, and task knowledge stored in Zep's graph memory.

## Features

- Procedure search using Zep's graph memory
- Operational knowledge retrieval
- Workflow and task documentation access
- MCP protocol implementation for seamless integration
- NPX support for easy installation and usage

## Prerequisites

- Node.js (v16 or higher)
- Zep Cloud account and API key

## Installation

### Using NPX (Recommended)

You can run the server directly using NPX without installing it globally:

```bash
npx procedure-memory-mcp-server@latest
```

### Manual Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd procedure-memory-mcp-server
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

## Configuration

### MCP Configuration (Claude Desktop)

To use this server with Claude Desktop, add the following to your MCP settings file:

**Location:** `~/.cursor/mcp.json` (for Cursor) or `~/Library/Application Support/Claude/claude_desktop_config.json` (for Claude Desktop)

```json
{
  "mcpServers": {
    "procedure-search": {
      "command": "node",
      "args": [
        "/path/to/syiaOpsMemory/dist/index.js"
      ],
      "env": {
        "ZEP_API_KEY": "your-zep-api-key-here",
        "USER_ID": "your-user-id-here"
      }
    }
  }
}
```

Replace:
- `/path/to/syiaOpsMemory` with the actual path to your project directory
- `your-zep-api-key-here` with your Zep Cloud API key
- `your-user-id-here` with your Zep user ID (e.g., "syiaOpsMemory")

### Environment Variables

The server supports the following environment variables:

```env
ZEP_API_KEY=<your-zep-api-key>      # Zep Cloud API key for memory storage
USER_ID=<your-user-id>               # User ID for Zep memory queries
```

### Using NPX with Environment Variables

When using NPX, you can pass environment variables:

```bash
ZEP_API_KEY="your-key" USER_ID="your-id" npx procedure-memory-mcp-server@latest
```

## Running the Server

### Development Mode

```bash
npm run dev
```

### Production Mode

```bash
npm start
```

## API Endpoints

The server implements the following MCP endpoints:

### Tools

- `tools.list` - List available tools
- `tools.call` - Call a specific tool

Available Tools:
- `search_procedures` - Search for procedures, documentation, and operational knowledge stored in memory. This tool searches across all procedure episodes, finding relevant documentation based on your query.

Example tool usage:
```json
{
  "method": "tools.call",
  "params": {
    "name": "search_procedures",
    "arguments": {
      "query": "database connection setup",
      "numResults": 3
    }
  }
}
```

## Testing

To test the server functionality, you can use the MCP inspector or interact with the server directly through stdio. Here are some example requests in JSON format that you can send to the server:

1. List Tools:
```json
{
  "method": "tools.list"
}
```

2. Search Procedures:
```json
{
  "method": "tools.call",
  "params": {
    "name": "search_procedures",
    "arguments": {
      "query": "authentication workflow",
      "numResults": 5
    }
  }
}
```

To test the server:

1. Start the server:
```bash
npm start
```

2. Send the JSON requests to the server's stdin. The server will respond through stdout.

Note: The server uses the Model Context Protocol (MCP) with stdio transport, which means it communicates through standard input/output rather than HTTP endpoints. This is the standard way MCP servers operate, allowing for direct integration with AI models and other MCP-compatible systems.

## Development

### Project Structure

```
src/
├── index.ts              # Main server entry point
├── tools/               # Tool definitions and handlers
│   ├── index.ts         # Tool registry
│   └── procedureSearch.ts # Zep-based procedure search
└── utils/              # Utility functions and configurations
    └── config.ts       # Configuration management
```

### Adding New Tools

To add new tools, create them in the `src/tools/` directory and register them in `src/tools/index.ts`.

## Memory Management

This server uses Zep Cloud for storing and retrieving operational procedures and knowledge. The search functionality leverages Zep's graph-based memory system to find the most relevant episodes based on:

- Semantic similarity
- Reference count
- Relationship strength
- Contextual relevance

## Troubleshooting

### Common Issues

1. **"Cannot find module" error**
   - Make sure you've built the project: `npm run build`
   - Verify the path in your MCP config points to the `dist/index.js` file

2. **"Server disconnected" error**
   - Check that your ZEP_API_KEY is valid
   - Ensure the USER_ID matches your Zep account
   - Look at the MCP logs for detailed error messages

3. **No results returned**
   - Verify your Zep memory contains data for the specified USER_ID
   - Try broader search queries
   - Check the relevance threshold settings

### Restart After Configuration Changes

After updating your MCP configuration:
1. Close Claude Desktop/Cursor completely
2. Reopen the application
3. The server should now be available in the MCP tools

## License

MIT