@ebowwa/state-mcp 1.0.0

package/README.md

@@ -0,0 +1,141 @@
+# @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
+
+```bash
+# 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`):
+
+```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
+
+```typescript
+// 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
+
+```bash
+# Install dependencies
+bun install
+
+# Build
+bun run build
+
+# Run
+bun run start
+```
+
+## Related Packages
+
+- [`@ebowwa/state`](https://www.npmjs.com/package/@ebowwa/state) - Core state management library
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@ebowwa/state-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for state management using @ebowwa/state core library",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "state-mcp": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "state-management",
+    "context",
+    "claude",
+    "ai"
+  ],
+  "author": "Ebowwa Labs <labs@ebowwa.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@ebowwa/state": "^0.1.1",
+    "@modelcontextprotocol/sdk": "^1.12.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ebowwa/codespaces.git",
+    "directory": "packages/mcp/state-mcp"
+  },
+  "homepage": "https://github.com/ebowwa/codespaces/tree/main/packages/mcp/state-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/ebowwa/codespaces/issues"
+  },
+  "files": [
+    "dist"
+  ]
+}