@jive-ai/cli 0.0.26 → 0.0.31

package/docs/mcp.md

@@ -1,899 +0,0 @@
-# MCP Server Commands
-
-MCP (Model Context Protocol) servers extend Claude's capabilities by providing additional tools. Jive helps teams share and manage MCP server configurations across projects.
-
-## Overview
-
-MCP server management in Jive allows you to:
-- Share MCP server configurations with your team
-- Pull team MCP servers to your local project
-- Push local MCP servers to share with your team
-- Add new MCP servers interactively
-- Remove MCP servers from the team
-- Merge team configurations with local ones
-
-## MCP Configuration Format
-
-MCP servers are configured in `.mcp.json` at the project root:
-
-```json
-{
-  "mcpServers": {
-    "weather-api": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-weather"],
-      "env": {
-        "API_KEY": "your-api-key"
-      }
-    },
-    "file-system": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
-    },
-    "jive-mcp": {
-      "command": "npx",
-      "args": ["-y", "jive-cli", "mcp", "start"],
-      "env": {
-        "JIVE_API_URL": "https://next.getjive.app",
-        "JIVE_TEAM_ID": "team-abc123",
-        "JIVE_AUTH_TOKEN": "your-token"
-      }
-    }
-  }
-}
-```
-
-**Server Configuration Fields:**
-- `command` (required) - Executable command (e.g., `npx`, `node`, `python`)
-- `args` (optional) - Array of command arguments
-- `env` (optional) - Object of environment variables
-
-## Commands
-
-### `jive mcp list`
-
-List all MCP servers for the active team.
-
-**Usage:**
-```bash
-jive mcp list
-```
-
-**Requirements:**
-- Must be authenticated
-- Must be in a Jive-initialized project
-
-**Process:**
-1. Gets active team ID from `.jive/config.json`
-2. Fetches team MCP servers from API (`GET /api/teams/{teamId}/mcp-servers`)
-3. Displays formatted list
-
-**Output:**
-```
-Team MCP servers:
-
-weather-api (mcp-123)
-  Command: npx -y @modelcontextprotocol/server-weather
-  Environment: API_KEY
-
-file-system (mcp-456)
-  Command: npx -y @modelcontextprotocol/server-filesystem /allowed
-  Environment: (none)
-
-database (mcp-789)
-  Command: node server.js
-  Environment: DB_HOST, DB_USER, DB_PASS
-```
-
-**Notes:**
-- Shows server name, ID, command, and environment variables
-- Environment variable values are not displayed (security)
-- Only shows servers for the active team
-
-**Error Conditions:**
-- Not authenticated
-- Project not initialized
-- Network connectivity issues
-
-**Implementation:** `src/commands/mcp.ts` (mcpCommands.list)
-
----
-
-### `jive mcp pull`
-
-Download team MCP servers to local `.mcp.json`.
-
-**Usage:**
-```bash
-jive mcp pull [--merge]
-```
-
-**Options:**
-- `--merge` - Merge with local servers instead of replacing (default: replace)
-
-**Requirements:**
-- Must be authenticated
-- Must be in a Jive-initialized project
-
-**Process:**
-1. Creates backup at `.mcp.json.backup`
-2. Fetches remote MCP servers from team API
-3. **If `--merge`:**
-   - Merges with local servers
-   - Remote servers take precedence on conflicts
-   - Preserves local-only servers
-4. **If not merge (default):**
-   - Replaces all servers except `jive-mcp`
-   - `jive-mcp` server is always preserved
-5. Writes updated `.mcp.json`
-
-**Output (replace mode):**
-```bash
-jive mcp pull
-```
-```
-Creating backup: .mcp.json.backup
-Pulling MCP servers from team...
-
-✓ weather-api
-✓ file-system
-✓ database
-
-Downloaded 3 MCP servers
-Preserved jive-mcp server
-```
-
-**Output (merge mode):**
-```bash
-jive mcp pull --merge
-```
-```
-Creating backup: .mcp.json.backup
-Merging MCP servers from team...
-
-✓ weather-api (updated)
-✓ file-system (updated)
-✓ database (new)
-✓ local-only-server (preserved)
-
-Merged 3 team servers with 1 local server
-```
-
-**Before Pull:**
-```json
-{
-  "mcpServers": {
-    "jive-mcp": { "command": "npx", "args": ["jive-cli", "mcp", "start"] },
-    "local-only-server": { "command": "node", "args": ["local.js"] }
-  }
-}
-```
-
-**After Pull (replace):**
-```json
-{
-  "mcpServers": {
-    "jive-mcp": { "command": "npx", "args": ["jive-cli", "mcp", "start"] },
-    "weather-api": { "command": "npx", "args": ["-y", "server-weather"] },
-    "file-system": { "command": "npx", "args": ["-y", "server-filesystem"] }
-  }
-}
-```
-
-**After Pull (--merge):**
-```json
-{
-  "mcpServers": {
-    "jive-mcp": { "command": "npx", "args": ["jive-cli", "mcp", "start"] },
-    "local-only-server": { "command": "node", "args": ["local.js"] },
-    "weather-api": { "command": "npx", "args": ["-y", "server-weather"] },
-    "file-system": { "command": "npx", "args": ["-y", "server-filesystem"] }
-  }
-}
-```
-
-**Notes:**
-- Always creates a backup before modifying `.mcp.json`
-- `jive-mcp` server is never removed
-- Use `--merge` to preserve local-only servers
-- Restart Claude Code after pulling to apply changes
-
-**Error Conditions:**
-- Not authenticated
-- Project not initialized
-- Network connectivity issues
-- File system permission errors
-
-**Implementation:** `src/commands/mcp.ts` (mcpCommands.pull)
-
----
-
-### `jive mcp push`
-
-Upload local MCP servers to the team.
-
-**Usage:**
-```bash
-jive mcp push [--force]
-```
-
-**Options:**
-- `--force` - Force push without conflict checks (not fully implemented)
-
-**Requirements:**
-- Must be authenticated
-- Must be in a Jive-initialized project
-- Must have `.mcp.json` file
-
-**Process:**
-1. Reads `.mcp.json` from project root
-2. For each server (except `jive-mcp`):
-   - Attempts to create server on team via `POST /api/teams/{teamId}/mcp-servers`
-   - Ignores errors (servers may already exist)
-3. Displays summary of uploaded servers
-
-**Output:**
-```bash
-jive mcp push
-```
-```
-Pushing MCP servers to team...
-
-✓ weather-api
-✓ file-system
-⊘ database (already exists)
-
-Pushed 2 servers, skipped 1
-```
-
-**Notes:**
-- Does not update existing servers (create-only currently)
-- Skips `jive-mcp` server (reserved by Jive)
-- Safe to run multiple times (idempotent)
-- Other team members must run `jive mcp pull` to get changes
-
-**Error Conditions:**
-- Not authenticated
-- Project not initialized
-- `.mcp.json` not found
-- Invalid JSON in `.mcp.json`
-- Network connectivity issues
-
-**Implementation:** `src/commands/mcp.ts` (mcpCommands.push)
-
----
-
-### `jive mcp add <name>`
-
-Add a new MCP server to the team interactively.
-
-**Usage:**
-```bash
-jive mcp add <name>
-```
-
-**Arguments:**
-- `<name>` (required) - Name for the MCP server (e.g., `weather-api`)
-
-**Requirements:**
-- Must be authenticated
-- Must be in a Jive-initialized project
-
-**Interactive Prompts:**
-- **Command:** Executable to run (e.g., `npx`, `node`, `python`)
-- **Arguments:** Comma-separated list of arguments
-- **Environment variables:** Key=value pairs, one per line (empty line to finish)
-
-**Process:**
-1. Prompts for server configuration
-2. Creates server on team via `POST /api/teams/{teamId}/mcp-servers`
-3. Adds server to local `.mcp.json`
-4. Creates `.mcp.json` if it doesn't exist
-
-**Output:**
-```bash
-jive mcp add weather-api
-```
-```
-? Command: npx
-? Arguments (comma-separated): -y, @modelcontextprotocol/server-weather
-? Environment variables (KEY=VALUE, empty line to finish):
-  API_KEY=your-api-key-here
-
-✓ MCP server added to team
-✓ Added to .mcp.json
-
-Restart Claude Code to use the new server.
-```
-
-**Created Configuration:**
-```json
-{
-  "mcpServers": {
-    "weather-api": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-weather"],
-      "env": {
-        "API_KEY": "your-api-key-here"
-      }
-    }
-  }
-}
-```
-
-**Examples:**
-
-**Node.js server:**
-```bash
-jive mcp add my-server
-# Command: node
-# Arguments: dist/server.js
-# Environment: PORT=3000
-```
-
-**Python server:**
-```bash
-jive mcp add python-tools
-# Command: python
-# Arguments: -m, mcp_server
-# Environment: PYTHONPATH=/path/to/modules
-```
-
-**NPM package:**
-```bash
-jive mcp add filesystem
-# Command: npx
-# Arguments: -y, @modelcontextprotocol/server-filesystem, /allowed/path
-# Environment: (none)
-```
-
-**Notes:**
-- Server is immediately available to team members (after they pull)
-- Must restart Claude Code to use the new server
-- Environment variables are stored in `.mcp.json` (keep secrets safe!)
-
-**Error Conditions:**
-- Not authenticated
-- Project not initialized
-- Server name already exists
-- Network connectivity issues
-- Invalid command or arguments
-
-**Implementation:** `src/commands/mcp.ts` (mcpCommands.add)
-
----
-
-### `jive mcp remove <name-or-id>`
-
-Remove an MCP server from the team.
-
-**Usage:**
-```bash
-jive mcp remove <name-or-id>
-```
-
-**Arguments:**
-- `<name-or-id>` (required) - Name or ID of MCP server to remove
-
-**Requirements:**
-- Must be authenticated
-- Must be in a Jive-initialized project
-
-**Interactive Prompts:**
-- **Confirmation:** "Are you sure you want to remove {name}?" (Y/n)
-
-**Process:**
-1. Fetches team MCP servers to find match by name or ID
-2. Displays server details
-3. Prompts for confirmation
-4. Deletes from server via `DELETE /api/mcp-servers/{id}`
-5. Removes from local `.mcp.json` if present
-
-**Output:**
-```bash
-jive mcp remove weather-api
-```
-```
-Found MCP server: weather-api
-Command: npx -y @modelcontextprotocol/server-weather
-ID: mcp-123
-
-? Are you sure you want to remove weather-api? (Y/n) Yes
-
-✓ Removed from team
-✓ Removed from .mcp.json
-
-Restart Claude Code to apply changes.
-```
-
-**By ID:**
-```bash
-jive mcp remove mcp-123
-```
-
-**Before Removal:**
-```json
-{
-  "mcpServers": {
-    "weather-api": { "command": "npx", "args": ["..."] },
-    "file-system": { "command": "npx", "args": ["..."] }
-  }
-}
-```
-
-**After Removal:**
-```json
-{
-  "mcpServers": {
-    "file-system": { "command": "npx", "args": ["..."] }
-  }
-}
-```
-
-**Notes:**
-- Removes from team (affects all team members)
-- Also removes from local `.mcp.json` if present
-- Cannot remove `jive-mcp` server (reserved)
-- Other team members will still have local configuration until they pull
-
-**Error Conditions:**
-- Not authenticated
-- Project not initialized
-- MCP server not found
-- Attempting to remove `jive-mcp`
-- User cancels confirmation
-- Network connectivity issues
-
-**Implementation:** `src/commands/mcp.ts` (mcpCommands.remove)
-
----
-
-### `jive mcp start`
-
-Start the Jive MCP server for stdio communication.
-
-**Usage:**
-```bash
-jive mcp start
-```
-
-**Requirements:**
-- Must be authenticated
-- Must have active team configured
-
-**Process:**
-1. Initializes MCP server with stdio transport
-2. Provides tools for Claude Code integration:
-   - `search_subagents` - Search for subagents by name/description
-   - `call_subagent` - Get subagent prompt with user input
-   - `search_tools` - Search for MCP tools across servers
-   - `get_tools` - Get TypeScript definitions for tools
-   - `call_tool` - Execute TypeScript code that calls MCP tools
-3. Manages connections to other MCP servers
-4. Handles tool execution and code transpilation
-
-**Output:**
-```
-Starting Jive MCP server...
-Server running on stdio
-```
-
-**Notes:**
-- This command is typically run automatically by Claude Code
-- Not intended for direct user invocation
-- Configured in `.mcp.json` by `jive init`
-- Runs in the background as a Claude Code MCP server
-
-**Tools Provided:**
-
-**`search_subagents`:**
-```json
-{
-  "query": "code review"
-}
-```
-Returns matching subagents.
-
-**`call_subagent`:**
-```json
-{
-  "name": "code-reviewer",
-  "input": "Review this code..."
-}
-```
-Returns subagent prompt with injected input.
-
-**`search_tools`:**
-```json
-{
-  "query": "file"
-}
-```
-Returns MCP tools matching the query.
-
-**`get_tools`:**
-```json
-{
-  "server": "weather-api",
-  "tools": ["get_forecast"]
-}
-```
-Returns TypeScript definitions for the tools.
-
-**`call_tool`:**
-```json
-{
-  "code": "const forecast = await getWeatherForecast({city: 'NYC'});"
-}
-```
-Transpiles and executes TypeScript code calling MCP tools.
-
-**Error Conditions:**
-- Not authenticated
-- No active team configured
-- Port already in use (stdio conflicts)
-
-**Implementation:** `src/mcp/index.ts`
-
----
-
-## MCP Workflows
-
-### Adding a Public MCP Server
-
-1. **Find the MCP server package:**
-   - Search npm: `@modelcontextprotocol/server-*`
-   - Check MCP documentation
-
-2. **Add to team:**
-   ```bash
-   jive mcp add weather-api
-   ```
-   - Command: `npx`
-   - Arguments: `-y, @modelcontextprotocol/server-weather`
-   - Environment: `API_KEY=your-key`
-
-3. **Team members pull:**
-   ```bash
-   jive mcp pull
-   ```
-
-4. **Restart Claude Code**
-
-### Adding a Custom MCP Server
-
-1. **Develop your MCP server:**
-   ```javascript
-   // server.js
-   const { Server } = require('@modelcontextprotocol/sdk/server');
-   // ... implement server
-   ```
-
-2. **Add to team:**
-   ```bash
-   jive mcp add my-custom-server
-   ```
-   - Command: `node`
-   - Arguments: `path/to/server.js`
-   - Environment: `CONFIG_PATH=...`
-
-3. **Share with team:**
-   - Team members run `jive mcp pull`
-   - They need access to the server code (shared repo)
-
-### Managing Environment Variables
-
-**Development vs Production:**
-
-`.mcp.json` (committed):
-```json
-{
-  "mcpServers": {
-    "weather-api": {
-      "command": "npx",
-      "args": ["-y", "server-weather"],
-      "env": {
-        "API_KEY": "${WEATHER_API_KEY}"
-      }
-    }
-  }
-}
-```
-
-`.env` (not committed):
-```
-WEATHER_API_KEY=actual-secret-key
-```
-
-**Security best practices:**
-- Don't commit API keys to `.mcp.json`
-- Use environment variable references: `${VAR_NAME}`
-- Store actual values in `.env` (add to `.gitignore`)
-- Share setup instructions with team
-
-### Syncing MCP Configurations
-
-**Initial setup (new team member):**
-```bash
-# After jive init
-jive mcp pull
-# Creates .mcp.json with team servers
-```
-
-**Regular updates:**
-```bash
-# Pull team changes
-jive mcp pull --merge
-# Preserves local-only servers
-
-# Restart Claude Code
-```
-
-**Sharing local additions:**
-```bash
-# Add server locally (edit .mcp.json or use jive mcp add)
-jive mcp push
-# Shares with team
-```
-
-## MCP Server Configuration
-
-### Server Types
-
-**npm packages:**
-```json
-{
-  "command": "npx",
-  "args": ["-y", "@org/package-name", "...args"]
-}
-```
-
-**Node.js scripts:**
-```json
-{
-  "command": "node",
-  "args": ["path/to/server.js"]
-}
-```
-
-**Python modules:**
-```json
-{
-  "command": "python",
-  "args": ["-m", "module_name"]
-}
-```
-
-**Executables:**
-```json
-{
-  "command": "/path/to/executable",
-  "args": ["--option", "value"]
-}
-```
-
-### Environment Variables
-
-**Simple values:**
-```json
-{
-  "env": {
-    "API_KEY": "your-key",
-    "PORT": "3000"
-  }
-}
-```
-
-**References to shell environment:**
-```json
-{
-  "env": {
-    "API_KEY": "${WEATHER_API_KEY}",
-    "HOME": "${HOME}"
-  }
-}
-```
-
-**Multiple variables:**
-```json
-{
-  "env": {
-    "DB_HOST": "localhost",
-    "DB_PORT": "5432",
-    "DB_USER": "admin",
-    "DB_PASS": "${DB_PASSWORD}"
-  }
-}
-```
-
-### The jive-mcp Server
-
-**Special server added by `jive init`:**
-```json
-{
-  "jive-mcp": {
-    "command": "npx",
-    "args": ["-y", "jive-cli", "mcp", "start"],
-    "env": {
-      "JIVE_API_URL": "https://next.getjive.app",
-      "JIVE_TEAM_ID": "team-abc123",
-      "JIVE_AUTH_TOKEN": "your-token"
-    }
-  }
-}
-```
-
-**Purpose:**
-- Provides subagent execution tools
-- Enables MCP tool discovery and execution
-- Connects Claude Code to Jive platform
-
-**Notes:**
-- Never pushed to team (excluded by `jive mcp push`)
-- Never removed by `jive mcp pull` (always preserved)
-- Re-created/updated by `jive init`
-
-## Troubleshooting
-
-### MCP Server Not Loading
-
-**Symptoms:**
-- Server appears in `.mcp.json` but tools not available
-- Claude Code doesn't recognize server
-
-**Solutions:**
-1. Restart Claude Code
-2. Check server configuration:
-   ```bash
-   jive doctor
-   ```
-3. Verify command is valid:
-   ```bash
-   npx -y @modelcontextprotocol/server-weather
-   ```
-4. Check Claude Code MCP logs
-
-### Environment Variables Not Working
-
-**Symptoms:**
-- Server fails to start
-- Authentication errors
-
-**Solutions:**
-1. Check variable references:
-   ```json
-   "env": {
-     "API_KEY": "${MY_API_KEY}"  // Shell env var
-   }
-   ```
-
-2. Set variables in shell:
-   ```bash
-   export MY_API_KEY=actual-key
-   ```
-
-3. Or use `.env` file (if supported)
-
-4. Or use literal values (not recommended for secrets):
-   ```json
-   "env": {
-     "API_KEY": "actual-key"  // Not recommended
-   }
-   ```
-
-### Pull Overwrites Local Changes
-
-**Symptoms:**
-- Local-only servers removed after `jive mcp pull`
-
-**Solutions:**
-1. Always use `--merge` to preserve local servers:
-   ```bash
-   jive mcp pull --merge
-   ```
-
-2. Restore from backup:
-   ```bash
-   cp .mcp.json.backup .mcp.json
-   ```
-
-3. Re-add local servers:
-   ```bash
-   jive mcp add my-local-server
-   ```
-
-### Backup File Issues
-
-**Symptoms:**
-- `.mcp.json.backup` accumulating
-
-**Solutions:**
-```bash
-# Remove old backups
-rm .mcp.json.backup
-
-# Add to .gitignore
-echo ".mcp.json.backup" >> .gitignore
-```
-
-## Security Considerations
-
-### API Keys and Secrets
-
-**Never commit secrets to version control:**
-
-❌ **Bad:**
-```json
-{
-  "env": {
-    "API_KEY": "sk-actual-secret-key"
-  }
-}
-```
-
-✅ **Good:**
-```json
-{
-  "env": {
-    "API_KEY": "${WEATHER_API_KEY}"
-  }
-}
-```
-
-**Share setup instructions:**
-```markdown
-## Setup
-
-1. Create `.env` file:
-   ```
-   WEATHER_API_KEY=your-key-here
-   ```
-
-2. Pull MCP servers:
-   ```bash
-   jive mcp pull
-   ```
-
-3. Restart Claude Code
-```
-
-### Team Sharing
-
-- MCP server configurations are shared with the team
-- Environment variable values in `.mcp.json` are visible to all team members
-- Use variable references for secrets
-- Document required environment variables for the team
-
-## Related Commands
-
-- [`jive init`](./init.md#jive-init) - Adds `jive-mcp` server
-- [`jive sync`](./sync.md#jive-sync) - Pulls all team resources including MCP servers
-- [`jive team switch`](./team.md#jive-team-switch) - Change active team (affects which servers you see)
-- [`jive doctor`](./init.md#jive-doctor) - Verify MCP configuration
-
-## API Endpoints
-
-**MCP Server Management:**
-- `GET /api/teams/{teamId}/mcp-servers` - List team MCP servers
-- `POST /api/teams/{teamId}/mcp-servers` - Create MCP server
-- `GET /api/mcp-servers/{id}` - Get MCP server details
-- `PUT /api/mcp-servers/{id}` - Update MCP server
-- `DELETE /api/mcp-servers/{id}` - Delete MCP server
-
-## Implementation Details
-
-**Source Files:**
-- Main implementation: `src/commands/mcp.ts`
-- MCP server: `src/mcp/index.ts`
-- Config helpers: `src/lib/config.ts`
-- File utilities: `src/lib/fs-utils.ts`
-
-**Key Functions:**
-- `mcpCommands.list()` - Lists team MCP servers
-- `mcpCommands.pull()` - Downloads MCP servers
-- `mcpCommands.push()` - Uploads MCP servers
-- `mcpCommands.add()` - Creates new MCP server
-- `mcpCommands.remove()` - Deletes MCP server
-- `startMcpServer()` - Starts Jive MCP server
-- `loadMcpConfig()` - Reads `.mcp.json`
-- `saveMcpConfig()` - Writes `.mcp.json`