433 lines
8.6 KiB
Markdown
433 lines
8.6 KiB
Markdown
# CLI Reference
|
|
|
|
Quick reference for MXCP command-line interface.
|
|
|
|
## Core Commands
|
|
|
|
### mxcp init
|
|
|
|
Initialize new MXCP project.
|
|
|
|
```bash
|
|
mxcp init # Current directory
|
|
mxcp init my-project # New directory
|
|
mxcp init --bootstrap # With examples
|
|
mxcp init --project=myapp --profile=dev
|
|
```
|
|
|
|
### mxcp serve
|
|
|
|
Start MCP server.
|
|
|
|
```bash
|
|
mxcp serve # Use config defaults
|
|
mxcp serve --transport stdio # For Claude Desktop
|
|
mxcp serve --transport http --port 8080
|
|
mxcp serve --profile production
|
|
mxcp serve --sql-tools true # Enable SQL query tools
|
|
mxcp serve --readonly # Read-only database
|
|
mxcp serve --stateless # For serverless deployment
|
|
mxcp serve --debug # Debug mode
|
|
```
|
|
|
|
### mxcp list
|
|
|
|
List available endpoints.
|
|
|
|
```bash
|
|
mxcp list # All endpoints
|
|
mxcp list --json-output # JSON format
|
|
mxcp list --profile prod # Specific profile
|
|
```
|
|
|
|
### mxcp run
|
|
|
|
Execute endpoint.
|
|
|
|
```bash
|
|
# Tools
|
|
mxcp run tool my_tool --param name=value
|
|
|
|
# Resources
|
|
mxcp run resource my_resource --param id=123
|
|
|
|
# Prompts
|
|
mxcp run prompt my_prompt --param text="hello"
|
|
|
|
# Complex parameters from JSON file
|
|
mxcp run tool analyze --param data=@input.json
|
|
|
|
# With user context
|
|
mxcp run tool secure_data --user-context '{"role": "admin"}'
|
|
|
|
# Read-only mode
|
|
mxcp run tool query_data --readonly
|
|
```
|
|
|
|
## Quality Commands
|
|
|
|
### mxcp validate
|
|
|
|
Check structure and types.
|
|
|
|
```bash
|
|
mxcp validate # All endpoints
|
|
mxcp validate my_tool # Specific endpoint
|
|
mxcp validate --json-output # JSON format
|
|
mxcp validate --readonly # Read-only database
|
|
```
|
|
|
|
### mxcp test
|
|
|
|
Run endpoint tests.
|
|
|
|
```bash
|
|
mxcp test # All tests
|
|
mxcp test tool my_tool # Specific endpoint
|
|
mxcp test --user-context '{"role": "admin"}'
|
|
mxcp test --user-context @user.json
|
|
mxcp test --json-output
|
|
mxcp test --readonly
|
|
```
|
|
|
|
### mxcp lint
|
|
|
|
Check metadata quality.
|
|
|
|
```bash
|
|
mxcp lint # All endpoints
|
|
mxcp lint --severity warning # Warnings only
|
|
mxcp lint --severity info # All issues
|
|
mxcp lint --json-output
|
|
```
|
|
|
|
### mxcp evals
|
|
|
|
Test LLM behavior.
|
|
|
|
```bash
|
|
mxcp evals # All eval suites
|
|
mxcp evals safety_checks # Specific suite
|
|
mxcp evals --model gpt-4o # Override model
|
|
mxcp evals --user-context '{"role": "user"}'
|
|
mxcp evals --json-output
|
|
```
|
|
|
|
## Data Commands
|
|
|
|
### mxcp query
|
|
|
|
Execute SQL directly.
|
|
|
|
```bash
|
|
mxcp query "SELECT * FROM users"
|
|
mxcp query "SELECT * FROM sales WHERE region = $region" --param region=US
|
|
mxcp query --file query.sql
|
|
mxcp query --file query.sql --param date=@dates.json
|
|
mxcp query "SELECT COUNT(*) FROM data" --json-output
|
|
mxcp query "SELECT * FROM users" --readonly
|
|
```
|
|
|
|
### mxcp dbt
|
|
|
|
Run dbt commands.
|
|
|
|
```bash
|
|
mxcp dbt run # Run all models
|
|
mxcp dbt run --select model
|
|
mxcp dbt test # Run tests
|
|
mxcp dbt docs generate # Generate docs
|
|
mxcp dbt-config # Generate dbt config
|
|
mxcp dbt-config --dry-run # Preview config
|
|
```
|
|
|
|
### mxcp drift-snapshot
|
|
|
|
Create baseline snapshot.
|
|
|
|
```bash
|
|
mxcp drift-snapshot # Default profile
|
|
mxcp drift-snapshot --profile prod
|
|
mxcp drift-snapshot --force # Overwrite existing
|
|
mxcp drift-snapshot --dry-run
|
|
```
|
|
|
|
### mxcp drift-check
|
|
|
|
Check for changes.
|
|
|
|
```bash
|
|
mxcp drift-check # Use default baseline
|
|
mxcp drift-check --baseline path/to/snapshot.json
|
|
mxcp drift-check --profile prod
|
|
mxcp drift-check --json-output
|
|
mxcp drift-check --readonly
|
|
```
|
|
|
|
## Monitoring Commands
|
|
|
|
### mxcp log
|
|
|
|
Query audit logs.
|
|
|
|
```bash
|
|
# Basic queries
|
|
mxcp log # Recent logs
|
|
mxcp log --since 1h # Last hour
|
|
mxcp log --since 2d # Last 2 days
|
|
|
|
# Filtering
|
|
mxcp log --tool my_tool # Specific tool
|
|
mxcp log --resource my_resource
|
|
mxcp log --prompt my_prompt
|
|
mxcp log --type tool # By type
|
|
mxcp log --status error # Errors only
|
|
mxcp log --status success # Successes only
|
|
mxcp log --policy deny # Denied by policy
|
|
|
|
# Output
|
|
mxcp log --limit 50 # Limit results
|
|
mxcp log --json # JSON format
|
|
mxcp log --export-csv audit.csv
|
|
mxcp log --export-duckdb audit.db
|
|
|
|
# Combined filters
|
|
mxcp log --since 1d --tool my_tool --status error
|
|
```
|
|
|
|
### mxcp log-cleanup
|
|
|
|
Apply retention policies.
|
|
|
|
```bash
|
|
mxcp log-cleanup # Apply retention
|
|
mxcp log-cleanup --dry-run # Preview deletions
|
|
mxcp log-cleanup --profile prod
|
|
mxcp log-cleanup --json
|
|
```
|
|
|
|
## Common Options
|
|
|
|
Available for most commands:
|
|
|
|
```bash
|
|
--profile PROFILE # Use specific profile
|
|
--json-output # Output as JSON
|
|
--debug # Debug logging
|
|
--readonly # Read-only database access
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
```bash
|
|
# Config location (use project-local config)
|
|
export MXCP_CONFIG=./config.yml
|
|
# Or for global config (user manually copies)
|
|
# export MXCP_CONFIG=~/.mxcp/config.yml
|
|
|
|
# Default profile
|
|
export MXCP_PROFILE=production
|
|
|
|
# Debug mode
|
|
export MXCP_DEBUG=1
|
|
|
|
# Read-only mode
|
|
export MXCP_READONLY=1
|
|
|
|
# Override database path
|
|
export MXCP_DUCKDB_PATH=/path/to/custom.duckdb
|
|
|
|
# Disable analytics
|
|
export MXCP_DISABLE_ANALYTICS=1
|
|
```
|
|
|
|
## Time Formats
|
|
|
|
For `--since` option:
|
|
|
|
```bash
|
|
10s # 10 seconds
|
|
5m # 5 minutes
|
|
2h # 2 hours
|
|
1d # 1 day
|
|
3w # 3 weeks
|
|
```
|
|
|
|
## Exit Codes
|
|
|
|
- `0` - Success
|
|
- `1` - Error or validation failure
|
|
- `2` - Invalid arguments
|
|
|
|
## Configuration Options
|
|
|
|
### Project Structure Enforcement
|
|
|
|
**CRITICAL**: MXCP enforces organized directory structure. Files in wrong locations are **ignored**.
|
|
|
|
Required structure:
|
|
- Tools: `tools/*.yml`
|
|
- Resources: `resources/*.yml`
|
|
- Prompts: `prompts/*.yml`
|
|
- Python: `python/*.py`
|
|
- SQL: `sql/*.sql`
|
|
|
|
Use `mxcp init --bootstrap` to create proper structure.
|
|
|
|
### Profile Configuration (mxcp-site.yml)
|
|
|
|
```yaml
|
|
mxcp: 1
|
|
project: my-project
|
|
|
|
# Generic SQL tools for database exploration (optional)
|
|
sql_tools:
|
|
enabled: true
|
|
|
|
profiles:
|
|
default:
|
|
database:
|
|
path: data.duckdb
|
|
|
|
production:
|
|
# Authentication
|
|
auth:
|
|
provider: github
|
|
# OAuth config in project config.yml
|
|
|
|
# Audit logging
|
|
audit:
|
|
enabled: true
|
|
path: audit/logs.jsonl
|
|
retention_days: 90
|
|
|
|
# OpenTelemetry observability
|
|
telemetry:
|
|
enabled: true
|
|
endpoint: "http://otel-collector:4318"
|
|
|
|
# Policy enforcement
|
|
policies:
|
|
strict_mode: true
|
|
|
|
# Database
|
|
database:
|
|
path: /app/data/production.duckdb
|
|
```
|
|
|
|
### Configuration Details
|
|
|
|
**Telemetry (OpenTelemetry)**:
|
|
```yaml
|
|
profiles:
|
|
production:
|
|
telemetry:
|
|
enabled: true
|
|
endpoint: "http://localhost:4318" # OTLP endpoint
|
|
# Optional: service name
|
|
service_name: "my-mxcp-server"
|
|
```
|
|
|
|
Provides:
|
|
- Distributed tracing for requests
|
|
- Performance metrics
|
|
- Integration with Jaeger, Grafana, etc.
|
|
|
|
**Stateless Mode** (`--stateless` flag):
|
|
- For Claude.ai and serverless deployments
|
|
- Disables state that persists across requests
|
|
- Use for horizontal scaling
|
|
|
|
**SQL Tools**:
|
|
|
|
Generic SQL tools provide built-in database exploration capabilities for LLMs:
|
|
- **`list_tables`** - View all available tables
|
|
- **`get_table_schema`** - Examine table structure and columns
|
|
- **`execute_sql_query`** - Run custom SQL queries
|
|
|
|
Enable via config file (recommended):
|
|
```yaml
|
|
# mxcp-site.yml
|
|
sql_tools:
|
|
enabled: true
|
|
```
|
|
|
|
Or via command-line flag:
|
|
```bash
|
|
mxcp serve --sql-tools true # Enable
|
|
mxcp serve --sql-tools false # Disable (default)
|
|
```
|
|
|
|
**Use cases:**
|
|
- Natural language data exploration
|
|
- Ad-hoc analysis and discovery
|
|
- Prototyping query patterns
|
|
- Working with dbt-transformed data
|
|
|
|
**Security:** Generic SQL tools allow arbitrary SQL execution. Use read-only database connections and consider policy-based restrictions for production deployments.
|
|
|
|
**Example:** See `assets/project-templates/covid_owid/` for complete implementation.
|
|
|
|
## Common Workflows
|
|
|
|
### Development
|
|
|
|
```bash
|
|
# Initialize with proper directory structure
|
|
mxcp init --bootstrap
|
|
|
|
# Validate structure
|
|
mxcp validate
|
|
|
|
# Test functionality
|
|
mxcp test
|
|
|
|
# Check documentation
|
|
mxcp lint
|
|
|
|
# Run locally with debug
|
|
mxcp serve --debug
|
|
```
|
|
|
|
### Deployment
|
|
|
|
```bash
|
|
# Create snapshot
|
|
mxcp drift-snapshot --profile prod
|
|
|
|
# Run tests
|
|
mxcp test --profile prod
|
|
|
|
# Run evals
|
|
mxcp evals --profile prod
|
|
|
|
# Deploy
|
|
mxcp serve --profile prod
|
|
```
|
|
|
|
### Monitoring
|
|
|
|
```bash
|
|
# Check drift
|
|
mxcp drift-check --profile prod
|
|
|
|
# View recent errors
|
|
mxcp log --since 1h --status error
|
|
|
|
# Export audit trail
|
|
mxcp log --since 7d --export-duckdb audit.db
|
|
|
|
# Clean old logs
|
|
mxcp log-cleanup
|
|
```
|
|
|
|
## Tips
|
|
|
|
1. **Use --debug** for troubleshooting
|
|
2. **Test locally** before deployment
|
|
3. **Use profiles** for different environments
|
|
4. **Export logs** for analysis
|
|
5. **Run drift checks** in CI/CD
|
|
6. **Validate before committing**
|
|
7. **Use --readonly** for query tools
|