npm package: @shoutoutlabs/memory-bank-graph-mcp
Description: MCP server for Memory Bank Graph - provides intelligent codebase analysis and dependency mapping for Cursor IDE
Author: ShoutOUT Labs
Latest version: 0.1.3

# @shoutoutlabs/memory-bank-graph-mcp

[![npm version](https://badge.fury.io/js/%40shoutoutlabs%2Fmemory-bank-graph-mcp.svg)](https://badge.fury.io/js/%40shoutoutlabs%2Fmemory-bank-graph-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server that provides intelligent codebase analysis and dependency mapping for Cursor IDE. This package creates and manages a SQLite-based graph database of your project's structure, dependencies, and relationships.

## Features

- **Intelligent Project Detection**: Automatically detects project root and creates memory database
- **Graph Database**: SQLite-based graph storage for project structure and dependencies
- **MCP Integration**: Full Model Context Protocol compliance for Cursor IDE
- **Auto-Initialization**: Automatic database schema creation and setup
- **Flexible Configuration**: Command-line and environment variable options

## Installation

```bash
npm install @shoutoutlabs/memory-bank-graph-mcp
```

## Quick Start

### 1. Initialize the Database

```bash
# Auto-detect project root and initialize database
npx @shoutoutlabs/memory-bank-graph-mcp --init

# Or using npm script
npm run init
```

### 2. Start the MCP Server

```bash
# Start the server (auto-detects project root)
npx @shoutoutlabs/memory-bank-graph-mcp

# Or using npm script
npm start
```

## Configuration

### Auto-Detection Strategy

The server automatically detects your project root by looking for these indicators:

- `package.json`
- `.git` directory
- `src` directory
- `memory-bank` directory
- `memory-bank-graph` directory

### Manual Configuration

#### Command Line Options

```bash
# Specify project root
npx @shoutoutlabs/memory-bank-graph-mcp --project-root=/path/to/your/project

# Initialize database
npx @shoutoutlabs/memory-bank-graph-mcp --init --project-root=/path/to/your/project
```

#### Environment Variables

```bash
# Set project root
export PROJECT_ROOT=/path/to/your/project
npx @shoutoutlabs/memory-bank-graph-mcp

# Set custom database path
export MCP_SQLITE_PATH=/path/to/custom/database.db
npx @shoutoutlabs/memory-bank-graph-mcp
```

## Database Location

The memory database is automatically created in your project's memory directory structure:

```
your-project/
├── memory/
│   └── db/
│       └── memory.db
└── ...
```

## MCP Tools

This server provides the following MCP tools:

### Graph Management
- `graph_init` - Initialize or update database schema
- `graph_upsert_version` - Create or update graph nodes
- `graph_add_edge` - Add relationships between nodes
- `graph_search_nodes` - Search for nodes in the graph
- `graph_current_requirements` - Get current project requirements

### Project Management
- `project_create` - Create or version a project node
- `service_create` - Create a service and link to project
- `requirement_propose` - Propose new requirements
- `requirement_accept` - Accept requirements into canonical
- `decision_record` - Record architectural decisions
- `slo_upsert` - Create or update Service Level Objectives

### Utilities
- `snapshot_create` - Create project snapshots
- `housekeeping_expire_ephemeral` - Clean up expired nodes

## Integration with Cursor IDE

Add this to your Cursor MCP configuration:

```json
{
  "mcpServers": {
    "memory-bank-graph": {
      "command": "npx",
      "args": ["@shoutoutlabs/memory-bank-graph-mcp"],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}
```

## Development

### Prerequisites

- Node.js 18.0.0 or higher
- npm or yarn

### Local Development

```bash
# Clone the repository
git clone https://github.com/shoutoutlabs/memory-bank-graph.git
cd memory-bank-graph/local-graph-mcp

# Install dependencies
npm install

# Start development server
npm start

# Initialize database
npm run init
```

## API Reference

### Command Line Interface

```bash
npx @shoutoutlabs/memory-bank-graph-mcp [options]

Options:
  --project-root=<path>    Set project root directory
  --init                   Initialize database schema
  --help                   Show help information
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PROJECT_ROOT` | Project root directory | Auto-detected |
| `MCP_SQLITE_PATH` | Custom database path | `{PROJECT_ROOT}/memory/db/memory.db` |

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- 📖 [Documentation](https://github.com/shoutoutlabs/memory-bank-graph#readme)
- 🐛 [Issue Tracker](https://github.com/shoutoutlabs/memory-bank-graph/issues)
- 💬 [Discussions](https://github.com/shoutoutlabs/memory-bank-graph/discussions)

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.

---

Made with ❤️ by [ShoutOUT Labs](https://shoutoutlabs.com)