mcpctl/docs/getting-started.md

# Getting Started with mcpctl

## Prerequisites

- Node.js >= 20.0.0
- pnpm >= 9.0.0
- PostgreSQL (for mcpd)
- Docker or Podman (for container management)

## Installation

```bash
# Clone the repository
git clone <repo-url>
cd mcpctl

# Install dependencies
pnpm install

# Generate Prisma client
pnpm --filter @mcpctl/db exec prisma generate

# Build all packages
pnpm build
```

## Quick Start

### 1. Start the Database

```bash
# Start PostgreSQL via Docker Compose
pnpm db:up

# Run database migrations
pnpm --filter @mcpctl/db exec prisma db push
```

### 2. Start the Daemon

```bash
cd src/mcpd
pnpm dev
```

The daemon starts on `http://localhost:4444` by default.

### 3. Use the CLI

```bash
# Check daemon status
mcpctl status

# Register an MCP server
mcpctl apply config.yaml

# Or use the interactive wizard
mcpctl setup my-server

# List registered servers
mcpctl get servers

# Start an instance
mcpctl instance start <server-id>

# Check instance status
mcpctl instance list

# View instance logs
mcpctl instance logs <instance-id>
```

### 4. Generate .mcp.json for Claude

```bash
# Create a project
mcpctl project create my-workspace

# Assign profiles to project
mcpctl project set-profiles <project-id> <profile-id-1> <profile-id-2>

# Generate .mcp.json
mcpctl claude generate <project-id>

# Or manually add servers
mcpctl claude add my-server -c npx -a -y @my/mcp-server
```

## Example Configuration

Create a `config.yaml` file:

```yaml
servers:
  - name: slack
    description: Slack MCP server
    transport: STDIO
    packageName: "@anthropic/slack-mcp"
    env:
      - name: SLACK_TOKEN
        valueFrom:
          secretRef:
            name: slack-secrets
            key: token

  - name: github
    description: GitHub MCP server
    transport: STDIO
    packageName: "@anthropic/github-mcp"

profiles:
  - name: default
    server: slack
    envOverrides:
      SLACK_TOKEN: "xoxb-your-token"

projects:
  - name: dev-workspace
    description: Development workspace
```

Apply it:

```bash
mcpctl apply config.yaml
```

## Running Tests

```bash
# Run all tests
pnpm test:run

# Run tests for a specific package
pnpm --filter @mcpctl/cli test:run
pnpm --filter @mcpctl/mcpd test:run
pnpm --filter @mcpctl/local-proxy test:run

# Run tests with coverage
pnpm test:coverage

# Typecheck
pnpm typecheck

# Lint
pnpm lint
```

## Development

```bash
# Watch mode for tests
pnpm test

# Build in watch mode
cd src/cli && pnpm dev
```