core/cli
8
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: add comprehensive CLI documentation for issue #4

Browse source 
Added comprehensive documentation for core/cli including:

1. Complete CLI Reference (cli-reference.md)
   - All 30 commands with detailed descriptions
   - Subcommands, flags, and usage examples
   - Organized by category (Development, AI/ML, DevOps, etc.)

2. Build Variants System (build-variants.md)
   - How to create custom builds (minimal, dev, devops, ai/ml)
   - Three methods: import commenting, multiple main.go, build tags
   - External variant repos (core/php, core/ci)
   - Size optimization and compression tips

3. MCP Integration (mcp-integration.md)
   - Model Context Protocol server setup
   - All available tools (file ops, RAG, metrics, process mgmt, WebView/CDP)
   - Transport modes (stdio, TCP)
   - Security considerations and workspace restriction
   - Use cases and troubleshooting

4. Environment Variables (environment-variables.md)
   - All supported environment variables
   - Configuration file locations (user, project, registry)
   - CORE_CONFIG_* mapping system
   - Service-specific vars (MCP, RAG, ML, Git, etc.)
   - Best practices and troubleshooting

5. Updated Navigation
   - Enhanced cmd/index.md with categories and quick links
   - Updated mkdocs.yml with new documentation pages

Fixes #4

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Clotho 2026-02-16 17:16:48 +00:00
parent a4ad18fa2a
commit 36f790ed22
6 changed files with 2946 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

367
docs/build-variants.md Normal file
View file

@ -0,0 +1,367 @@
# Build Variants
The Core CLI supports a modular build system that allows you to create different binary variants with different feature sets. This is useful for creating minimal builds, specialized builds, or builds tailored to specific use cases.
## Overview
The variant system works through Go's module system and selective import statements in `main.go`. By commenting out or including specific import statements, you can control which commands are included in the final binary.
## Available Variants
### Full Build (Default)
The default build includes all commands and features. This is the standard build used for development and general-purpose use.
**Size:** ~50-100 MB (depending on platform)
**Included:** All commands documented in [CLI Reference](cli-reference.md)
### Minimal Build
A minimal build includes only essential commands, suitable for resource-constrained environments or when you only need basic functionality.
**Recommended commands for minimal build:**
- `config` - Configuration management
- `help` - Help system
- `doctor` - Environment checks
- `test` - Basic testing
### Specialized Builds
You can create specialized builds for specific use cases:
#### Developer Build
Focus on development workflow commands:
- `dev` - Development workflow
- `git` - Git operations
- `go` - Go development
- `test` - Testing
- `qa` - Quality assurance
- `docs` - Documentation
#### DevOps Build
Focus on infrastructure and deployment:
- `deploy` - Deployment management
- `prod` - Production infrastructure
- `vm` - Virtual machine management
- `unifi` - Network management
- `monitor` - Security monitoring
#### AI/ML Build
Focus on AI and machine learning operations:
- `ai` - AI task management
- `ml` - ML pipeline
- `rag` - RAG system
- `mcp` - MCP server
- `collect` - Data collection
## How to Create a Variant
### Method 1: Comment Out Imports in main.go
Edit `main.go` and comment out the commands you don't want:
```go
package main
import (
"forge.lthn.ai/core/go/pkg/cli"
// Essential commands
_ "forge.lthn.ai/core/cli/cmd/config"
_ "forge.lthn.ai/core/cli/cmd/help"
_ "forge.lthn.ai/core/cli/cmd/doctor"
// Development commands
_ "forge.lthn.ai/core/cli/cmd/dev"
_ "forge.lthn.ai/core/cli/cmd/go"
_ "forge.lthn.ai/core/cli/cmd/test"
// Comment out to exclude:
// _ "forge.lthn.ai/core/cli/cmd/ai"
// _ "forge.lthn.ai/core/cli/cmd/ml"
// _ "forge.lthn.ai/core/cli/cmd/deploy"
// etc.
)
func main() {
cli.Main()
}
```
Then build:
```bash
task cli:build
```
### Method 2: Create Multiple main.go Files
Create separate entry points for different variants:
```bash
# Directory structure
cmd/
core/ # Full build
main.go
core-minimal/ # Minimal build
main.go
core-dev/ # Developer build
main.go
core-devops/ # DevOps build
main.go
```
Each `main.go` includes only the relevant imports for that variant.
Build specific variant:
```bash
cd cmd/core-minimal
go build -o ../../bin/core-minimal .
```
### Method 3: Build Tags
Use Go build tags to conditionally include commands:
```go
//go:build !minimal
// +build !minimal
package ai
// Command registration...
```
Build with tags:
```bash
# Full build
go build -o bin/core .
# Minimal build
go build -tags minimal -o bin/core-minimal .
```
## External Variant Repositories
The Core CLI architecture supports external command repositories that can be optionally included. These are commented out in `main.go` by default:
```go
// Variant repos (optional — comment out to exclude)
// _ "forge.lthn.ai/core/php"
// _ "forge.lthn.ai/core/ci"
```
### Currently Available External Repos
#### core/php (Archived)
PHP and Laravel development commands. **Note:** This has been moved to its own repository and is no longer included by default.
#### core/ci (Archived)
CI/CD pipeline commands. **Note:** This has been moved to its own repository and is no longer included by default.
To include these in your build:
1. Add the module to your `go.mod`:
```bash
go get forge.lthn.ai/core/php@latest
```
2. Uncomment the import in `main.go`:
```go
_ "forge.lthn.ai/core/php"
```
3. Rebuild:
```bash
task cli:build
```
## Build Optimization
### Size Optimization
For smaller binaries, use the release build with stripped symbols:
```bash
task cli:build:release
```
This uses the following ldflags:
```
-s -w # Strip debug info and symbol table
```
### Compression
Further reduce binary size with UPX:
```bash
# Install UPX
# macOS: brew install upx
# Linux: apt-get install upx-ucl
# Compress binary
upx --best --lzma bin/core
```
**Note:** Compressed binaries may trigger antivirus false positives and won't work with code signing on macOS.
## Version Information
All builds include embedded version information via ldflags:
```bash
# View version
core --version
# Build with custom version
go build -ldflags "-X forge.lthn.ai/core/go/pkg/cli.AppVersion=1.2.3" .
```
The Taskfile automatically sets version info from git tags:
```yaml
LDFLAGS_BASE: >-
-X {{.PKG}}.AppVersion={{.SEMVER_VERSION}}
-X {{.PKG}}.BuildCommit={{.SEMVER_COMMIT}}
-X {{.PKG}}.BuildDate={{.SEMVER_DATE}}
-X {{.PKG}}.BuildPreRelease={{.SEMVER_PRERELEASE}}
```
## Examples
### Create a Minimal Developer Build
1. Edit `main.go`:
```go
package main
import (
"forge.lthn.ai/core/go/pkg/cli"
_ "forge.lthn.ai/core/cli/cmd/config"
_ "forge.lthn.ai/core/cli/cmd/dev"
_ "forge.lthn.ai/core/cli/cmd/doctor"
_ "forge.lthn.ai/core/cli/cmd/git"
_ "forge.lthn.ai/core/cli/cmd/go"
_ "forge.lthn.ai/core/cli/cmd/help"
_ "forge.lthn.ai/core/cli/cmd/test"
)
func main() {
cli.Main()
}
```
2. Build:
```bash
task cli:build:release
```
3. Result: ~20-30 MB binary with only development commands
### Create an AI/ML Specialist Build
1. Edit `main.go`:
```go
package main
import (
"forge.lthn.ai/core/go/pkg/cli"
_ "forge.lthn.ai/core/cli/cmd/ai"
_ "forge.lthn.ai/core/cli/cmd/collect"
_ "forge.lthn.ai/core/cli/cmd/config"
_ "forge.lthn.ai/core/cli/cmd/daemon"
_ "forge.lthn.ai/core/cli/cmd/help"
_ "forge.lthn.ai/core/cli/cmd/mcp"
_ "forge.lthn.ai/core/cli/cmd/ml"
_ "forge.lthn.ai/core/cli/cmd/rag"
_ "forge.lthn.ai/core/cli/cmd/session"
)
func main() {
cli.Main()
}
```
2. Build:
```bash
task cli:build:release
```
3. Result: Binary optimized for AI/ML workflows
## Testing Variants
Test your variant to ensure all needed commands are present:
```bash
# Build variant
task cli:build
# Test available commands
./bin/core help
# Verify specific command
./bin/core dev --help
```
## Distribution
When distributing variant builds, use clear naming:
```bash
# Good naming examples
core-full-v1.2.3-linux-amd64
core-minimal-v1.2.3-darwin-arm64
core-dev-v1.2.3-windows-amd64.exe
```
Include a README describing what's included in each variant.
## Best Practices
1. **Document your variant** - Keep a record of which commands are included
2. **Test thoroughly** - Ensure all needed functionality is present
3. **Version consistently** - Use the same version numbering scheme
4. **Consider dependencies** - Some commands depend on others (e.g., `dev` uses `git`)
5. **Keep it simple** - Don't create too many variants unless necessary
6. **Use release builds** - Always use `-s -w` ldflags for distribution
## Troubleshooting
### Command Not Found
If a command is missing after building a variant:
1. Check that the import is uncommented in `main.go`
2. Verify the module is in `go.mod`
3. Run `go mod tidy`
4. Rebuild with `task cli:build`
### Build Errors
If you get import errors:
1. Ensure all required modules are in `go.mod`
2. Run `go mod download`
3. Check for version conflicts with `go mod why`
### Large Binary Size
If your minimal build is still too large:
1. Use release build flags: `task cli:build:release`
2. Remove unused commands from imports
3. Consider using UPX compression (with caveats noted above)
4. Check for large embedded assets
## See Also
- [CLI Reference](cli-reference.md) - Complete command documentation
- [Configuration](configuration.md) - Configuration system
- [Getting Started](getting-started.md) - Installation and setup

1073
docs/cli-reference.md Normal file
View file

File diff suppressed because it is too large Load diff

107
docs/cmd/index.md
View file

@ -1,24 +1,66 @@
# Core CLI # Core CLI
Unified interface for Go/PHP development, multi-repo management, and deployment. Unified interface for development, multi-repo management, deployment, AI/ML operations, and infrastructure management.
## Commands ## Quick Links
- **[Complete CLI Reference](../cli-reference.md)** - Comprehensive documentation of all commands
- **[Build Variants](../build-variants.md)** - Create custom builds with different feature sets
- **[MCP Integration](../mcp-integration.md)** - Model Context Protocol server for AI assistants
- **[Environment Variables](../environment-variables.md)** - Configuration via environment
## Command Categories
### Development & Testing
| Command | Description |
|---------|-------------|
| [dev](dev/) | Multi-repo workflow + dev environment |
| [go](go/) | Go development tools |
| [test](test/) | Run Go tests with coverage |
| [qa](../cli-reference.md#qa) | Quality assurance workflow |
| [doctor](doctor/) | Check environment |
### AI & Machine Learning
| Command | Description | | Command | Description |
|---------|-------------| |---------|-------------|
| [ai](ai/) | AI agent task management and Claude integration | | [ai](ai/) | AI agent task management and Claude integration |
| [go](go/) | Go development tools | | AI ml | ML inference and training pipeline |
| [php](php/) | Laravel/PHP development tools | | AI mcp | Model Context Protocol server |
| [build](build/) | Build projects | | AI rag | RAG system for semantic search |
| [ci](ci/) | Publish releases | | AI collect | Data collection from external sources |
| [sdk](sdk/) | SDK validation and compatibility |
| [dev](dev/) | Multi-repo workflow + dev environment | ### Infrastructure & Deployment
| [pkg](pkg/) | Package management | | Command | Description |
|---------|-------------|
| AI deploy | Coolify deployment management |
| AI prod | Production infrastructure management |
| [vm](vm/) | LinuxKit VM management | | [vm](vm/) | LinuxKit VM management |
| AI unifi | UniFi network management |
| AI monitor | Security monitoring |
### Git & Forge
| Command | Description |
|---------|-------------|
| AI git | Root-level git workflow |
| AI forge | Forgejo instance management |
| AI gitea | Gitea instance management |
### Configuration & Utilities
| Command | Description |
|---------|-------------|
| AI config | Configuration management |
| AI crypt | Cryptographic utilities |
| [docs](docs/) | Documentation management | | [docs](docs/) | Documentation management |
| [setup](setup/) | Clone repos from registry | | AI help | Help documentation |
| [doctor](doctor/) | Check environment | | AI plugin | Plugin management |
| [test](test/) | Run Go tests with coverage | | AI workspace | Workspace configuration |
### Services
| Command | Description |
|---------|-------------|
| AI daemon | Background service management |
| AI session | Session recording and replay |
| AI lab | Homelab monitoring dashboard |
## Installation ## Installation
@ -29,3 +71,44 @@ go install forge.lthn.ai/core/cli/cmd/core@latest
Verify: `core doctor` Verify: `core doctor`
See [Getting Started](../getting-started.md) for all installation options. See [Getting Started](../getting-started.md) for all installation options.
## Build Variants
The Core CLI supports modular builds. You can create specialized variants:
- **Full** - All commands (default)
- **Minimal** - Essential commands only
- **Developer** - Development-focused
- **DevOps** - Infrastructure and deployment
- **AI/ML** - AI and machine learning operations
See [Build Variants](../build-variants.md) for details.
## Quick Start
```bash
# Check environment
core doctor
# Multi-repo workflow
core dev work
# Start MCP server for AI assistants
core mcp serve --workspace /path/to/project
# Run tests
core test
# Get help
core help
core <command> --help
```
## Documentation
- [CLI Reference](../cli-reference.md) - Complete command documentation
- [Build Variants](../build-variants.md) - Custom builds
- [MCP Integration](../mcp-integration.md) - MCP server setup
- [Environment Variables](../environment-variables.md) - Configuration options
- [Configuration](../configuration.md) - Config file reference
- [Getting Started](../getting-started.md) - Installation guide

735
docs/environment-variables.md Normal file
View file

@ -0,0 +1,735 @@
# Environment Variables
The Core CLI uses environment variables for configuration, authentication, and runtime behavior. This document lists all supported environment variables and their purposes.
## Configuration System
Environment variables are part of Core's layered configuration system:
1. **Command-line flags** (highest priority)
2. **Environment variables** ← This document
3. **Configuration file** (`~/.core/config.yaml`)
4. **Default values** (lowest priority)
## Configuration File Locations
### User Configuration
| File | Path | Purpose |
|------|------|---------|
| Main config | `~/.core/config.yaml` | User preferences and framework settings |
| Agentic config | `~/.core/agentic.yaml` | AI agent service configuration |
| MCP config | `~/.claude/mcp_config.json` | Claude Code MCP server settings |
| Keybindings | `~/.claude/keybindings.json` | Claude Code keyboard shortcuts |
### Project Configuration
Located in `.core/` directory of project root:
| File | Path | Purpose |
|------|------|---------|
| Build config | `.core/build.yaml` | Build targets and flags |
| Release config | `.core/release.yaml` | Release automation settings |
| CI config | `.core/ci.yaml` | CI pipeline configuration |
### Registry Configuration
Searched in order:
1. Current directory: `./repos.yaml`
2. Parent directories (walking up)
3. Home Code directory: `~/Code/host-uk/repos.yaml`
4. Config directory: `~/.config/core/repos.yaml`
## General Configuration
### CORE_CONFIG_*
Map configuration values to the YAML hierarchy using dot notation.
**Format:** `CORE_CONFIG_<KEY>=<value>`
After stripping the `CORE_CONFIG_` prefix, the remaining variable name is converted to lowercase and underscores are replaced with dots.
**Examples:**
```bash
# dev.editor: vim
export CORE_CONFIG_DEV_EDITOR=vim
# log.level: debug
export CORE_CONFIG_LOG_LEVEL=debug
# ai.model: gpt-4
export CORE_CONFIG_AI_MODEL=gpt-4
```
### NO_COLOR
Disable ANSI color output.
**Values:** Any value (presence disables colors)
**Example:**
```bash
export NO_COLOR=1
core doctor # No colored output
```
### CORE_DAEMON
Run application in daemon mode.
**Values:** `1` or `true`
**Example:**
```bash
export CORE_DAEMON=1
core mcp serve # Runs as background daemon
```
## MCP Server
### MCP_ADDR
TCP address for MCP server. If not set, MCP uses stdio transport.
**Format:** `host:port` or `:port`
**Default:** (stdio mode)
**Examples:**
```bash
# Listen on localhost:9999
export MCP_ADDR=localhost:9999
core mcp serve
# Listen on all interfaces (⚠️ not recommended)
export MCP_ADDR=:9999
core mcp serve
```
### CORE_MCP_TRANSPORT
MCP transport mode.
**Values:** `stdio`, `tcp`, `socket`
**Default:** `stdio`
**Example:**
```bash
export CORE_MCP_TRANSPORT=tcp
export CORE_MCP_ADDR=:9100
core daemon
```
### CORE_MCP_ADDR
Alternative to `MCP_ADDR` for daemon mode.
**Format:** Same as `MCP_ADDR`
### CORE_HEALTH_ADDR
Health check endpoint address for daemon mode.
**Format:** `host:port` or `:port`
**Default:** None (disabled)
**Example:**
```bash
export CORE_HEALTH_ADDR=:8080
core daemon
# Health check: curl http://localhost:8080/health
```
### CORE_PID_FILE
PID file location for daemon mode.
**Default:** (platform-specific temp directory)
**Example:**
```bash
export CORE_PID_FILE=/var/run/core-mcp.pid
core daemon
```
## Service APIs
### COOLIFY_TOKEN
API token for Coolify deployments.
**Example:**
```bash
export COOLIFY_TOKEN=your-api-token
core deploy servers
```
### AGENTIC_TOKEN
API token for Agentic AI services.
**Example:**
```bash
export AGENTIC_TOKEN=your-token
core ai tasks list
```
## Networking
### UNIFI_URL
UniFi controller URL.
**Format:** `https://host` or `https://host:port`
**Example:**
```bash
export UNIFI_URL=https://192.168.1.1
core unifi clients
```
### UNIFI_INSECURE
Skip TLS certificate verification for UniFi controller.
**Values:** `1`, `true`, `yes`
**Example:**
```bash
export UNIFI_INSECURE=1
export UNIFI_URL=https://192.168.1.1
core unifi devices
```
## Git/Forge Integration
### GITHUB_TOKEN
GitHub API token for operations requiring authentication.
**Note:** Usually set by GitHub CLI (`gh auth login`)
**Example:**
```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
core dev issues
```
### FORGEJO_URL
Forgejo instance URL.
**Example:**
```bash
export FORGEJO_URL=https://forge.example.com
core forge repos
```
### FORGEJO_TOKEN
Forgejo API token.
**Example:**
```bash
export FORGEJO_TOKEN=your-token
core forge issues
```
### GITEA_URL
Gitea instance URL.
**Example:**
```bash
export GITEA_URL=https://gitea.example.com
core gitea repos
```
### GITEA_TOKEN
Gitea API token.
**Example:**
```bash
export GITEA_TOKEN=your-token
core gitea issues
```
## RAG System
### QDRANT_HOST
Qdrant vector database host.
**Default:** `localhost`
**Example:**
```bash
export QDRANT_HOST=localhost
export QDRANT_PORT=6334
core rag collections list
```
### QDRANT_PORT
Qdrant gRPC port.
**Default:** `6334`
### OLLAMA_HOST
Ollama API host for embeddings.
**Default:** `localhost`
**Example:**
```bash
export OLLAMA_HOST=localhost
export OLLAMA_PORT=11434
core rag ingest --collection docs --path ./documentation
```
### OLLAMA_PORT
Ollama API port.
**Default:** `11434`
## ML Pipeline
### ML_API_URL
OpenAI-compatible API endpoint for ML operations.
**Example:**
```bash
export ML_API_URL=http://localhost:8000/v1
core ml score
```
### ML_JUDGE_URL
Judge model API URL (typically Ollama).
**Example:**
```bash
export ML_JUDGE_URL=http://localhost:11434
core ml score --judge-model llama2
```
### ML_JUDGE_MODEL
Judge model name for scoring.
**Default:** (varies by command)
**Example:**
```bash
export ML_JUDGE_MODEL=llama2:latest
core ml score
```
### INFLUX_URL
InfluxDB URL for metrics storage.
**Example:**
```bash
export INFLUX_URL=http://localhost:8086
export INFLUX_DB=metrics
core ml metrics
```
### INFLUX_DB
InfluxDB database name.
**Example:**
```bash
export INFLUX_DB=ml_metrics
core ml ingest
```
## Build System
### CGO_ENABLED
Enable or disable CGO for builds.
**Values:** `0` (disabled), `1` (enabled)
**Default:** `0` (Go default)
**Example:**
```bash
export CGO_ENABLED=1
task cli:build
```
### GOOS
Target operating system for cross-compilation.
**Values:** `linux`, `darwin`, `windows`, `freebsd`, etc.
**Example:**
```bash
export GOOS=linux
export GOARCH=amd64
task cli:build
```
### GOARCH
Target architecture for cross-compilation.
**Values:** `amd64`, `arm64`, `386`, `arm`, etc.
**Example:**
```bash
export GOOS=darwin
export GOARCH=arm64
task cli:build # Build for Apple Silicon
```
## Testing
### TEST_VERBOSE
Enable verbose test output.
**Values:** `1`, `true`
**Example:**
```bash
export TEST_VERBOSE=1
core test
```
### TEST_SHORT
Run short tests only.
**Values:** `1`, `true`
**Example:**
```bash
export TEST_SHORT=1
core test
```
### TEST_RACE
Enable race detector.
**Values:** `1`, `true`
**Example:**
```bash
export TEST_RACE=1
core test
```
## Infrastructure
### HETZNER_TOKEN
Hetzner Cloud API token.
**Example:**
```bash
export HETZNER_TOKEN=your-token
core prod status
```
### CLOUDNS_AUTH_ID
CloudNS authentication ID for DNS management.
**Example:**
```bash
export CLOUDNS_AUTH_ID=your-id
export CLOUDNS_AUTH_PASSWORD=your-password
core prod dns
```
### CLOUDNS_AUTH_PASSWORD
CloudNS authentication password.
## Virtual Machines
### LINUXKIT_PATH
Path to LinuxKit binary.
**Default:** `linuxkit` (from PATH)
**Example:**
```bash
export LINUXKIT_PATH=/usr/local/bin/linuxkit
core vm run
```
### VM_MEMORY
Default memory allocation for VMs.
**Format:** Integer (MB) or string with suffix (e.g., "2G")
**Default:** 2048 (2GB)
**Example:**
```bash
export VM_MEMORY=4096
core vm run my-vm
```
### VM_CPUS
Default CPU count for VMs.
**Default:** 2
**Example:**
```bash
export VM_CPUS=4
core vm run my-vm
```
## Development
### DEBUG
Enable debug logging.
**Values:** `1`, `true`
**Example:**
```bash
export DEBUG=1
core dev work
```
### LOG_LEVEL
Global log level.
**Values:** `debug`, `info`, `warn`, `error`
**Default:** `info`
**Example:**
```bash
export LOG_LEVEL=debug
core mcp serve
```
### EDITOR
Default text editor for interactive commands.
**Default:** `vim` or system default
**Example:**
```bash
export EDITOR=nvim
core dev commit # Uses neovim for editing
```
### PAGER
Default pager for command output.
**Default:** `less` or system default
**Example:**
```bash
export PAGER=bat
core help
```
## Best Practices
### 1. Use Config File for Persistent Settings
Environment variables are temporary. For persistent configuration, use `~/.core/config.yaml`:
```yaml
dev:
editor: nvim
log:
level: info
ai:
model: gpt-4
```
Set via CLI:
```bash
core config set dev.editor nvim
```
### 2. Use .env Files for Project-Specific Settings
Create `.env` in project root:
```bash
# .env
MCP_ADDR=localhost:9100
QDRANT_HOST=localhost
OLLAMA_HOST=localhost
```
Load with:
```bash
source .env
core mcp serve
```
Or use `direnv` for automatic loading.
### 3. Secure Sensitive Tokens
Never commit tokens to version control:
```bash
# .gitignore
.env
.env.local
*.token
```
Use environment-specific files:
```bash
.env.development
.env.staging
.env.production
```
### 4. Override in CI/CD
Set environment variables in CI/CD pipelines:
```yaml
# .github/workflows/test.yml
env:
CORE_CONFIG_LOG_LEVEL: debug
NO_COLOR: 1
```
### 5. Document Project Requirements
Create `.env.example` with required variables:
```bash
# .env.example
MCP_ADDR=localhost:9100
QDRANT_HOST=localhost
QDRANT_PORT=6334
OLLAMA_HOST=localhost
# FORGEJO_TOKEN=your-token-here
```
## Checking Configuration
### View Current Config
```bash
# All config values
core config list
# Specific value
core config get dev.editor
```
### View Config File Location
```bash
core config path
```
### Debug Environment Variables
```bash
# Show all CORE_* variables
env | grep CORE_
# Show all MCP-related variables
env | grep MCP
```
### Test Configuration
```bash
# Verify environment setup
core doctor --verbose
```
## Troubleshooting
### Variable Not Taking Effect
1. **Check priority:** Command flags override environment variables
```bash
# This flag takes priority
core mcp serve --workspace /path
```
2. **Verify variable is set:**
```bash
echo $MCP_ADDR
```
3. **Check for typos:**
```bash
# Wrong
export CORE_CONFIG_dev_editor=vim
# Correct
export CORE_CONFIG_DEV_EDITOR=vim
```
4. **Restart shell or reload:**
```bash
source ~/.bashrc # or ~/.zshrc
```
### Config File vs Environment Variables
If config file and environment variable conflict, environment variable wins:
```yaml
# ~/.core/config.yaml
log:
level: info
```
```bash
# This overrides the config file
export CORE_CONFIG_LOG_LEVEL=debug
core mcp serve # Uses debug level
```
### Case Sensitivity
Variable names are case-sensitive:
```bash
# Wrong
export mcp_addr=:9100
# Correct
export MCP_ADDR=:9100
```
## See Also
- [Configuration Reference](configuration.md) - Complete config file documentation
- [CLI Reference](cli-reference.md) - Command documentation
- [MCP Integration](mcp-integration.md) - MCP server setup
- [Getting Started](getting-started.md) - Installation and setup

658
docs/mcp-integration.md Normal file
View file

@ -0,0 +1,658 @@
# MCP Integration
The Core CLI includes a Model Context Protocol (MCP) server that provides file operations, RAG (Retrieval-Augmented Generation), metrics tracking, and process management tools for AI assistants like Claude Code.
## Overview
MCP is a protocol that allows AI assistants to interact with external tools and services. The Core CLI's MCP server exposes a rich set of tools for:
- **File Operations** - Read, write, edit, delete files and directories
- **RAG System** - Semantic search using Qdrant + Ollama embeddings
- **Metrics** - Record and query application metrics
- **Process Management** - Start, stop, and monitor processes
- **Language Detection** - Detect programming languages
- **WebSocket** - Real-time communication
- **WebView/CDP** - Browser automation via Chrome DevTools Protocol
## Quick Start
### Start MCP Server
**Stdio mode (for Claude Code):**
```bash
core mcp serve
```
**TCP mode:**
```bash
MCP_ADDR=localhost:9999 core mcp serve
```
**With workspace restriction:**
```bash
core mcp serve --workspace /path/to/project
```
### Configure in Claude Code
Add to your Claude Code MCP configuration (`~/.claude/mcp_config.json`):
```json
{
"mcpServers": {
"core-mcp": {
"command": "core",
"args": ["mcp", "serve"],
"env": {}
}
}
}
```
With workspace restriction:
```json
{
"mcpServers": {
"core-mcp": {
"command": "core",
"args": ["mcp", "serve", "--workspace", "/home/user/projects/myapp"],
"env": {}
}
}
}
```
## Transport Modes
### Stdio (Default)
Best for integration with Claude Code and other AI assistants that communicate via standard input/output.
```bash
core mcp serve
```
**Pros:**
- Simple setup
- Secure (no network exposure)
- Works with Claude Code out of the box
**Cons:**
- Single client only
- Process-coupled (client must manage server lifecycle)
### TCP
Best for network-based integrations or when you need multiple clients.
```bash
MCP_ADDR=localhost:9999 core mcp serve
```
**Pros:**
- Multiple clients can connect
- Server runs independently
- Can connect from remote machines (if exposed)
**Cons:**
- Requires network configuration
- No built-in authentication (use firewall/SSH tunnel)
- More complex setup
## Available Tools
### File Operations
#### file_read
Read contents of a file.
**Parameters:**
- `path` (string, required) - File path to read
**Example:**
```json
{
"name": "file_read",
"arguments": {
"path": "/path/to/file.txt"
}
}
```
#### file_write
Write content to a file (creates or overwrites).
**Parameters:**
- `path` (string, required) - File path to write
- `content` (string, required) - Content to write
**Example:**
```json
{
"name": "file_write",
"arguments": {
"path": "/path/to/file.txt",
"content": "Hello, world!"
}
}
```
#### file_edit
Edit a file by replacing old content with new content.
**Parameters:**
- `path` (string, required) - File path to edit
- `old_content` (string, required) - Content to find
- `new_content` (string, required) - Replacement content
**Example:**
```json
{
"name": "file_edit",
"arguments": {
"path": "/path/to/file.txt",
"old_content": "old text",
"new_content": "new text"
}
}
```
#### file_delete
Delete a file.
**Parameters:**
- `path` (string, required) - File path to delete
#### file_rename
Rename or move a file.
**Parameters:**
- `old_path` (string, required) - Current file path
- `new_path` (string, required) - New file path
#### file_exists
Check if a file or directory exists.
**Parameters:**
- `path` (string, required) - Path to check
**Returns:**
- `exists` (boolean)
- `is_dir` (boolean)
#### dir_list
List contents of a directory.
**Parameters:**
- `path` (string, required) - Directory path
- `recursive` (boolean, optional) - Recursively list subdirectories
#### dir_create
Create a directory (including parent directories).
**Parameters:**
- `path` (string, required) - Directory path to create
### RAG (Retrieval-Augmented Generation)
#### rag_ingest
Ingest documents into a collection for semantic search.
**Parameters:**
- `collection` (string, required) - Collection name
- `documents` (array, required) - Documents to ingest
- `id` (string) - Document ID
- `text` (string) - Document content
- `metadata` (object, optional) - Additional metadata
**Example:**
```json
{
"name": "rag_ingest",
"arguments": {
"collection": "documentation",
"documents": [
{
"id": "doc1",
"text": "This is a documentation page about MCP",
"metadata": {"type": "docs", "topic": "mcp"}
}
]
}
}
```
#### rag_query
Query a collection using semantic search.
**Parameters:**
- `collection` (string, required) - Collection name
- `query` (string, required) - Search query
- `limit` (integer, optional) - Maximum results (default: 5)
**Returns:**
Array of matching documents with scores.
#### rag_collections
List all RAG collections.
**Returns:**
Array of collection names and their document counts.
### Metrics
#### metrics_record
Record a metric value.
**Parameters:**
- `name` (string, required) - Metric name
- `value` (number, required) - Metric value
- `tags` (object, optional) - Metric tags/labels
- `timestamp` (string, optional) - ISO 8601 timestamp
**Example:**
```json
{
"name": "metrics_record",
"arguments": {
"name": "api.requests",
"value": 1,
"tags": {"endpoint": "/api/users", "status": "200"}
}
}
```
#### metrics_query
Query recorded metrics.
**Parameters:**
- `name` (string, optional) - Filter by metric name
- `tags` (object, optional) - Filter by tags
- `from` (string, optional) - Start time (ISO 8601)
- `to` (string, optional) - End time (ISO 8601)
### Language Detection
#### lang_detect
Detect programming language from code or filename.
**Parameters:**
- `content` (string, optional) - Code content
- `filename` (string, optional) - Filename
**Returns:**
- `language` (string) - Detected language
- `confidence` (number) - Detection confidence (0-1)
#### lang_list
List all supported languages.
**Returns:**
Array of supported language identifiers.
### Process Management
#### process_start
Start a new process.
**Parameters:**
- `id` (string, required) - Process identifier
- `command` (string, required) - Command to execute
- `args` (array, optional) - Command arguments
- `env` (object, optional) - Environment variables
- `cwd` (string, optional) - Working directory
**Example:**
```json
{
"name": "process_start",
"arguments": {
"id": "build-process",
"command": "go",
"args": ["build", "-o", "bin/app"],
"cwd": "/path/to/project"
}
}
```
#### process_stop
Stop a running process (SIGTERM).
**Parameters:**
- `id` (string, required) - Process identifier
#### process_kill
Force kill a process (SIGKILL).
**Parameters:**
- `id` (string, required) - Process identifier
#### process_list
List all managed processes.
**Returns:**
Array of process info (ID, command, status, PID).
#### process_output
Get output from a process.
**Parameters:**
- `id` (string, required) - Process identifier
- `tail` (integer, optional) - Number of recent lines
#### process_input
Send input to a process.
**Parameters:**
- `id` (string, required) - Process identifier
- `input` (string, required) - Input to send
### WebSocket
#### ws_start
Start a WebSocket hub server.
**Parameters:**
- `addr` (string, optional) - Listen address (default: ":8080")
**Returns:**
- `url` (string) - WebSocket server URL
#### ws_info
Get WebSocket server information.
**Returns:**
- `running` (boolean)
- `url` (string)
- `connections` (integer)
### WebView/CDP (Chrome DevTools Protocol)
#### webview_connect
Connect to Chrome/Chromium via CDP.
**Parameters:**
- `url` (string, required) - Debug URL (e.g., "http://localhost:9222")
#### webview_navigate
Navigate to a URL.
**Parameters:**
- `url` (string, required) - URL to navigate to
#### webview_click
Click an element.
**Parameters:**
- `selector` (string, required) - CSS selector
#### webview_type
Type text into an element.
**Parameters:**
- `selector` (string, required) - CSS selector
- `text` (string, required) - Text to type
#### webview_query
Query DOM for elements.
**Parameters:**
- `selector` (string, required) - CSS selector
**Returns:**
Array of matching elements.
#### webview_console
Get console logs.
**Returns:**
Array of console messages.
#### webview_eval
Evaluate JavaScript.
**Parameters:**
- `script` (string, required) - JavaScript code
**Returns:**
Evaluation result.
#### webview_screenshot
Take a screenshot.
**Parameters:**
- `full_page` (boolean, optional) - Full page screenshot
**Returns:**
- `data` (string) - Base64-encoded PNG
#### webview_wait
Wait for condition.
**Parameters:**
- `type` (string, required) - Condition type ("selector", "navigation", "timeout")
- `value` (string/number, required) - Condition value
#### webview_disconnect
Disconnect from CDP.
## Security Considerations
### Workspace Restriction
**Always** use `--workspace` flag when exposing MCP server to AI assistants:
```bash
core mcp serve --workspace /path/to/safe/directory
```
This restricts file operations to the specified directory and its subdirectories, preventing the AI from accessing sensitive files outside the project.
### File Operations
Without workspace restriction, the MCP server has full filesystem access. This is powerful but dangerous:
❌ **Never** run unrestricted in production:
```bash
core mcp serve # Full filesystem access!
```
✅ **Always** restrict to project directory:
```bash
core mcp serve --workspace /home/user/projects/myapp
```
### Network Exposure
When using TCP mode:
- **Localhost only** by default: `MCP_ADDR=localhost:9999`
- **Never** expose to public internet without authentication
- Use SSH tunnels for remote access
- Consider firewall rules to restrict access
### Process Management
Processes started via `process_start` run with the same permissions as the MCP server. Be cautious when:
- Running as root/administrator
- Executing untrusted commands
- Exposing process management to external clients
## Running as Daemon
Use the `daemon` command to run MCP server as a background service:
```bash
core daemon --mcp-transport tcp --mcp-addr :9100
```
With health endpoint:
```bash
core daemon --mcp-transport tcp --mcp-addr :9100 --health-addr :8080
```
Check health:
```bash
curl http://localhost:8080/health
```
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_ADDR` | TCP listen address | (stdio) |
| `CORE_MCP_TRANSPORT` | Transport mode (stdio, tcp) | stdio |
| `CORE_MCP_ADDR` | Alternative to MCP_ADDR | - |
| `CORE_HEALTH_ADDR` | Health check endpoint | - |
## Use Cases
### 1. Claude Code Integration
Enable Claude Code to read and modify files in your project:
```json
{
"mcpServers": {
"core": {
"command": "core",
"args": ["mcp", "serve", "--workspace", "${workspaceFolder}"]
}
}
}
```
### 2. Semantic Code Search
Ingest codebase into RAG system for semantic search:
```bash
# Start MCP server
core mcp serve --workspace /path/to/project
# Ingest code (via AI assistant)
# Use: rag_ingest with collection="code" and documents from source files
# Query code
# Use: rag_query with query="authentication logic"
```
### 3. Build Automation
Monitor build processes with real-time output:
```bash
# Start MCP with WebSocket
# Use: ws_start
# Use: process_start with command="go build"
# Subscribe to process output via WebSocket
```
### 4. Web Automation Testing
Automate browser testing:
```bash
# Start Chrome with remote debugging:
# google-chrome --remote-debugging-port=9222
# Use CDP tools:
# webview_connect url="http://localhost:9222"
# webview_navigate url="https://example.com"
# webview_click selector="#login-button"
# webview_screenshot
```
## Troubleshooting
### Server Won't Start
**Error:** Port already in use
```bash
# Check what's using the port
lsof -i :9999
# Kill the process or use different port
MCP_ADDR=:9100 core mcp serve
```
**Error:** Permission denied
```bash
# Don't use privileged ports (<1024) without sudo
# Use high ports instead:
MCP_ADDR=:9999 core mcp serve
```
### File Operations Fail
**Error:** File outside workspace
Make sure file paths are within the workspace:
```bash
# Workspace: /home/user/project
# ✅ OK: /home/user/project/src/main.go
# ❌ Fail: /etc/passwd
```
**Error:** Permission denied
Check file/directory permissions and MCP server user.
### RAG Not Working
**Error:** Qdrant connection failed
Ensure Qdrant is running:
```bash
# Start Qdrant (Docker)
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
```
**Error:** Ollama not available
Ensure Ollama is running:
```bash
# Start Ollama
ollama serve
# Pull embedding model
ollama pull nomic-embed-text
```
### Process Management Issues
**Error:** Process not found
List processes to verify ID:
```json
{"name": "process_list"}
```
**Error:** Process already exists
Use unique process IDs or stop existing process first.
## Performance Tips
1. **Use workspace restriction** - Reduces filesystem traversal overhead
2. **Batch RAG ingestion** - Ingest multiple documents in one call
3. **Limit query results** - Use `limit` parameter in rag_query
4. **Process output streaming** - Use WebSocket for real-time output
5. **Reuse connections** - Keep WebView CDP connection open for multiple operations
## See Also
- [CLI Reference](cli-reference.md) - Complete command documentation
- [Daemon Mode](daemon-mode.md) - Running MCP as a service
- [RAG System](rag-system.md) - Detailed RAG documentation
- [Environment Variables](environment-variables.md) - Configuration options

31
mkdocs.yml
View file

@ -50,19 +50,24 @@ nav:
- Workflows: workflows.md - Workflows: workflows.md
- CLI Reference: - CLI Reference:
- Overview: cmd/index.md - Overview: cmd/index.md
- AI: cmd/ai/index.md - Complete Reference: cli-reference.md
- Build: cmd/build/index.md - Build Variants: build-variants.md
- CI: cmd/ci/index.md - MCP Integration: mcp-integration.md
- Dev: cmd/dev/index.md - Environment Variables: environment-variables.md
- Go: cmd/go/index.md - Commands:
- PHP: cmd/php/index.md - AI: cmd/ai/index.md
- SDK: cmd/sdk/index.md - Build: cmd/build/index.md
- Setup: cmd/setup/index.md - CI: cmd/ci/index.md
- Doctor: cmd/doctor/index.md - Dev: cmd/dev/index.md
- Test: cmd/test/index.md - Go: cmd/go/index.md
- VM: cmd/vm/index.md - PHP: cmd/php/index.md
- Pkg: cmd/pkg/index.md - SDK: cmd/sdk/index.md
- Docs: cmd/docs/index.md - Setup: cmd/setup/index.md
- Doctor: cmd/doctor/index.md
- Test: cmd/test/index.md
- VM: cmd/vm/index.md
- Pkg: cmd/pkg/index.md
- Docs: cmd/docs/index.md
- Getting Started: - Getting Started:
- Installation: getting-started/installation.md - Installation: getting-started/installation.md
- Quick Start: getting-started/quickstart.md - Quick Start: getting-started/quickstart.md