@ebowwa/state-mcp

MCP server for state management using @ebowwa/state core library.

Overview

@ebowwa/state-mcp is a Model Context Protocol (MCP) server that provides persistent state management for AI coding assistants like Claude. Built on the @ebowwa/state core library with SQLite persistence.

Key Features

• Core Library: Uses @ebowwa/state for all state management logic
• Repository Pattern: Clean data access layer with SQLite backend
• Token-Aware Responses: Automatic response sizing to stay within MCP protocol limits
• Privacy Controls: Private state items that don't leak across sessions
• TypeScript: Full type safety throughout

Architecture

This MCP server is a thin wrapper around @ebowwa/state:

@ebowwa/state-mcp/
├── src/
│   ├── tools/          # MCP tool definitions & handlers
│   │   ├── definitions.ts  # Tool schemas
│   │   └── handlers.ts     # Tool implementations
│   ├── transports/     # MCP transport implementations
│   │   └── stdio.ts    # Stdio transport (Claude Desktop)
│   ├── index.ts        # Main entry point
│   └── cli.ts          # CLI entry point
└── package.json        # Depends on @ebowwa/state

Core logic is in @ebowwa/state:

• @ebowwa/state/core - Types, interfaces, errors
• @ebowwa/state/repositories - SQLite repositories
• @ebowwa/state/services - StateService business logic

Installation

# Install globally
npm install -g @ebowwa/state-mcp

# Or use with npx
npx @ebowwa/state-mcp

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "state": {
      "command": "npx",
      "args": ["-y", "@ebowwa/state-mcp"],
      "env": {
        "MCP_DB_PATH": "/path/to/state.db"
      }
    }
  }
}

Available Tools

| Tool | Description | |------|-------------| | state_save | Save or update a state item | | state_get | Get a state item by key | | state_query | Query state items with filters | | state_search | Search state items by text | | state_delete | Delete a state item | | state_list_keys | List all state keys | | session_info | Get current session info | | session_set | Switch to a different session | | session_list | List all sessions |

Tool Examples

// Save a state item
await mcp.call('state_save', {
  key: 'project:context',
  value: 'This is a React project with TypeScript',
  category: 'project',
  priority: 'high'
});

// Get a state item
await mcp.call('state_get', { key: 'project:context' });

// Query with filters
await mcp.call('state_query', {
  category: 'project',
  limit: 50
});

// Search
await mcp.call('state_search', {
  query: 'React',
  searchIn: ['key', 'value']
});

Configuration

Environment variables:

| Variable | Description | Default | |----------|-------------|---------| | MCP_DB_PATH | Path to SQLite database | ./state-mcp.db | | MCP_MAX_TOKENS | Maximum response tokens | 25000 | | MCP_TOKEN_SAFETY_BUFFER | Safety buffer (0-1) | 0.8 | | MCP_MIN_ITEMS | Minimum items to return | 1 | | MCP_MAX_ITEMS | Maximum items to return | 100 | | MCP_CHARS_PER_TOKEN | Char-to-token ratio | 3.5 | | LOG_LEVEL | Logging level | INFO |

Development

# Install dependencies
bun install

# Build
bun run build

# Run
bun run start

Related Packages

• @ebowwa/state - Core state management library

License

MIT