@usabledev/mcp-server/README.md

Usable CLI - Configure AI-powered knowledge management for development teams

# Usable CLI

A command-line tool to configure AI-powered knowledge management for development teams using Usable MCP integration.

## Overview

The Usable CLI provides two essential commands for setting up Usable MCP integration:

- **`init`** - Initialize your project with Usable configuration files and IDE integration
- **`install`** - Configure MCP server connection to Usable service

### agents.md Support

You can opt into the emerging `AGENTS.md` standard to provide cross-IDE guidance to AI agents.

Generate a starter `AGENTS.md` during init with:

```bash
npx @usabledev/mcp-server init --agents
```

This creates an `AGENTS.md` in your project root with a concise template aligned with this repo (TypeScript, Bun, MCP, Usable). Prefer `AGENTS.md` for shared guidance and keep IDE-specific files minimal.

This CLI enables AI assistants in your IDE to access and create memory fragments, search team knowledge, explore relationships, and maintain institutional knowledge across your development team.

## Installation

```bash
npm install -g @usabledev/mcp-server
```

Or use directly with npx:

```bash
npx @usabledev/mcp-server init
npx @usabledev/mcp-server install
```

## Commands

### Initialize Project

Initialize your project with Usable configuration:

```bash
npx @usabledev/mcp-server init
```

Options:

- `--ide <ide>` - IDE to configure (default: "cursor")
- `--output-dir <dir>` - Output directory for IDE config files (default: ".")
- `--workspace-id <id>` - Optional: Usable workspace ID to fetch fragment types
- `--api-token <token>` - Optional: Usable API access token to fetch fragment types
- `--usable-url <url>` - Optional: Usable API URL (default: "https://usable.dev")
- `--skip-auto-install` - Skip automatic MCP server installation (default: false)

#### Auto-Detection & Auto-Install Behavior

The `init` command includes intelligent auto-detection and auto-install features:

1. **IDE Detection**: Automatically detects existing MCP installations across multiple IDEs
2. **Auto-Install**: If no MCP installation is found, prompts to automatically install
3. **Smart Configuration**: Creates IDE-specific configuration files with repository context

**Supported IDEs for Auto-Detection:**

- **Cursor**: `~/.cursor/mcp.json`, `~/Library/Application Support/Cursor/`, `~/.config/cursor/`
- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **VS Code**: `~/Library/Application Support/Code/User/`, `~/.vscode/`
- **Cline**: `~/.cline/`, `~/Library/Application Support/Cline/`, `~/.config/cline/`
- **Zed**: `~/.zed/`, `~/Library/Application Support/Zed/`, `~/.config/zed/`
- **Windsurf**: `~/.windsurf/`, `~/Library/Application Support/Windsurf/`, `~/.config/windsurf/`
- **JetBrains IDEs**: `~/Library/Application Support/JetBrains/*/mcp.json`
- **Sublime Text**: `~/Library/Application Support/Sublime Text/Packages/User/`
- **Vim/Neovim**: `~/.vim/`, `~/.config/nvim/`
- **Emacs**: `~/.emacs.d/`

This command creates project-specific IDE configuration files:

- `.cursor/rules/usable.mdc` - Cursor IDE rules for Usable MCP integration

The configuration includes:

- Repository context and workspace mapping
- Fragment type definitions (knowledge, recipe, solution, template, code-snippet, styling)
- Available Usable MCP tools and usage guidelines
- Pre-task and post-task workflows for AI assistants

### Install MCP Server Connection

Configure MCP server connection to Usable:

```bash
npx @usabledev/mcp-server install --api-token <token>
```

Options:

- `--api-token <token>` - Usable API access token (required)
- `--usable-url <url>` - Usable API URL (default: "<https://usable.dev>")
- `--db-path <path>` - Custom database file path (default: "~/.usable-mcp/cache.db")
- `--local` - Configure local stdio MCP server (alias of `--force-legacy-mode`)
- `--force-legacy-mode` - Force stdio mode instead of modern HTTP streaming

This command:

1. Validates your Usable API connection and authentication
2. Configures the MCP server connection in your IDE's configuration
3. Sets up the remote HTTP transport to Usable MCP endpoint
4. Creates the database directory structure for local caching

### Run Local MCP Server (Legacy/Development)

For backwards compatibility or development purposes, run a local MCP server:

```bash
npx @usabledev/mcp-server server
```

Options:

- Environment variables:
  - `USABLE_API_TOKEN` or `USABLE_ACCESS_TOKEN` - Your API token (required)
  - `USABLE_BASE_URL` - Usable API URL (default: "<https://usable.dev>")  
  - `DEFAULT_WORKSPACE_ID` - Default workspace ID for operations

**Note**: This local server mode is provided for backwards compatibility with older IDE configurations. The remote MCP server connection (configured via `install` command) is recommended for optimal performance and reliability.

## Usage Workflow

1. **Get your API token** from the Usable web interface

2. **Initialize your project** (with workspace selection):

   ```bash
   npx @usabledev/mcp-server init --api-token <token>
   ```

   Or let the CLI prompt you for the token:

   ```bash
   npx @usabledev/mcp-server init
   ```

3. **Install MCP server connection**:

   ```bash
   npx @usabledev/mcp-server install --api-token <token>
   ```

4. **Restart your IDE** to load the MCP server configuration

## Usable MCP Tools

Once configured, AI assistants in your IDE will have access to these Usable tools:

### **Core Fragment Management**

- **`create_memory_fragment`** - Create new memory fragments (knowledge, recipe, solution, template, etc.)
- **`search_memory_fragments`** - AI-powered semantic search with similarity scores and filters
- **`get_memory_fragment_content`** - Retrieve full content of specific fragments by ID

### **Knowledge Discovery & Navigation**

- **`find_related_fragments`** - Discover fragments connected through shared tags and relationships
- **`explore_workspace_graph`** - Get knowledge graph visualization with nodes and relationships
- **`explore_tag_connections`** - Navigate fragments through specific tag relationships
- **`list_workspaces`** - List accessible workspaces with permissions

### **AI Assistant Workflow**

The tools are designed for a comprehensive knowledge management workflow:

1. **Search existing knowledge** first (`search_memory_fragments`)
2. **Explore relationships** if you need more context:
   - `explore_workspace_graph` - Overall knowledge structure
   - `explore_tag_connections` - Tag-based relationships
   - `find_related_fragments` - Fragment connections
3. **Create new fragments** when discovering novel solutions (`create_memory_fragment`)
4. **Iterate** until you have complete context for your task

## Configuration

### Remote MCP Server Configuration (Recommended)

The CLI updates your IDE's MCP configuration file (e.g., `~/.cursor/mcp.json`) with:

#### Standard Configuration (Cursor, Windsurf, Cline, etc.)

```json
{
  "mcpServers": {
    "usable": {
      "url": "https://usable.dev/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer your-api-token"
      }
    }
  }
}
```

#### VS Code Secure Configuration

VS Code supports secure credential prompting using input variables. The install command generates:

```json
{
  "servers": {
    "usable": {
      "url": "https://usable.dev/api/mcp?ide=vscode",
      "transport": "http",
      "headers": {
        "Authorization": "${input:usable-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "usable-api-key",
      "description": "Your Usable API Key",
      "password": true
    }
  ]
}
```

**Security Benefits:**

- API key is **not stored** in plaintext in the config file
- VS Code prompts for the key when the MCP server starts
- Password field is masked during input
- Credential is stored securely in VS Code's credential manager

### Local MCP Server Configuration (Legacy)

For backwards compatibility with IDEs requiring stdio MCP servers:

```json
{
  "mcpServers": {
    "usable-local": {
      "command": "npx",
      "args": ["@usabledev/mcp-server", "server"],
      "env": {
        "USABLE_API_TOKEN": "your-api-token",
        "USABLE_BASE_URL": "https://usable.dev"
      }
    }
  }
}
```

**Environment Variables for Local Server:**

- `USABLE_API_TOKEN` or `USABLE_ACCESS_TOKEN` - Your API token (required)
- `USABLE_BASE_URL` - Usable API URL (default: "<https://usable.dev>")
- `DEFAULT_WORKSPACE_ID` - Default workspace ID for operations

### Project Configuration Files

The `init` command creates project-specific configuration:

**`.cursor/rules/usable.mdc`** - Contains:

- Repository and workspace context mapping
- Fragment type definitions and IDs
- Complete Usable MCP tool documentation
- Usage guidelines and workflow instructions
- Pre-task and post-task workflows for AI assistants

### Database & Caching

The `install` command sets up local database structure:

- **Default location**: `~/.usable-mcp/cache.db`
- **Purpose**: Local caching and sync state management
- **Customizable**: Use `--db-path` to specify custom location

## Package Architecture

This package provides **two modes** of Usable MCP integration:

### 🌐 Remote MCP Server (Recommended)

The primary and recommended integration method:

- **What it is**: Direct HTTP connection from your IDE to Usable MCP service
- **Configuration**: Via `init` and `install` CLI commands  
- **Benefits**: Always up-to-date, no local server management, optimal performance
- **Integration Flow**: `IDE MCP Client` → `usable.dev/api/mcp`

### 🖥️ Local MCP Server (Legacy/Backwards Compatibility)

A local proxy server for older IDE configurations or special use cases:

```bash
# Run local MCP server mode
npx @usabledev/mcp-server server

# Or with specific configuration
USABLE_API_TOKEN="your-token" npx @usabledev/mcp-server server
```

**Local Server Features:**

- **Proxy Mode**: Acts as a local MCP server that proxies requests to Usable API
- **Stdio Transport**: Compatible with IDEs that require stdio MCP servers
- **Demo Mode**: Available only when no API token is provided (for testing MCP integration)
- **Error Handling**: Structured JSON-RPC error responses with proper error codes
- **Token Validation**: Fails immediately with clear error if provided token is invalid

**When to use Local Server:**

- ⚠️ **Legacy IDE configurations** that require stdio MCP servers
- 🔧 **Development and testing** of MCP integration
- 🌐 **Network-restricted environments** requiring local proxy

**Important Notes:**

- 🚨 **Use Remote MCP Server when possible** - it's faster, more reliable, and always current
- 📦 **Backwards Compatibility** - Local server mode is maintained for older IDE setups
- 🔄 **Real-time Sync** - Local server includes background streaming for real-time updates

### Integration Flow Comparison

**Remote (Recommended):**

1. **CLI Configuration** (`init` + `install`) →
2. **IDE MCP Client** →
3. **Usable MCP Service** (hosted at usable.dev)

**Local (Legacy):**

1. **CLI Configuration** (`init` + `install`) →
2. **Local MCP Server** (`npx @usabledev/mcp-server server`) →
3. **IDE MCP Client** (via stdio) →
4. **Usable MCP Service** (proxied)

## Troubleshooting

### Common Issues

**"API token is required"** - The `init` command requires an API token to fetch workspace information and fragment types. Provide it via:

- Command line: `--api-token <token>`
- Environment variable: `USABLE_API_TOKEN`
- Interactive prompt (CLI will ask if not provided)

**"Failed to connect to Usable service"** - Check:

- Network connectivity to usable.dev
- API token validity and permissions
- Workspace access permissions

**"MCP server not found in IDE"** - After installation:

- Restart your IDE completely
- Check MCP configuration file exists (e.g., `~/.cursor/mcp.json`)
- Verify the configuration JSON syntax is valid

## Requirements

- Node.js >= 18.0.0
- Valid Usable workspace and API credentials
- Compatible IDE with MCP support (Cursor, Claude Desktop, VS Code, etc.)

## License

MIT