docs: add comprehensive CLI documentation for issue #4
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:
parent
a4ad18fa2a
commit
36f790ed22
6 changed files with 2946 additions and 25 deletions
367
docs/build-variants.md
Normal file
367
docs/build-variants.md
Normal 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
1073
docs/cli-reference.md
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -1,24 +1,66 @@
|
|||
# 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 |
|
||||
|---------|-------------|
|
||||
| [ai](ai/) | AI agent task management and Claude integration |
|
||||
| [go](go/) | Go development tools |
|
||||
| [php](php/) | Laravel/PHP development tools |
|
||||
| [build](build/) | Build projects |
|
||||
| [ci](ci/) | Publish releases |
|
||||
| [sdk](sdk/) | SDK validation and compatibility |
|
||||
| [dev](dev/) | Multi-repo workflow + dev environment |
|
||||
| [pkg](pkg/) | Package management |
|
||||
| AI ml | ML inference and training pipeline |
|
||||
| AI mcp | Model Context Protocol server |
|
||||
| AI rag | RAG system for semantic search |
|
||||
| AI collect | Data collection from external sources |
|
||||
|
||||
### Infrastructure & Deployment
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| AI deploy | Coolify deployment management |
|
||||
| AI prod | Production infrastructure 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 |
|
||||
| [setup](setup/) | Clone repos from registry |
|
||||
| [doctor](doctor/) | Check environment |
|
||||
| [test](test/) | Run Go tests with coverage |
|
||||
| AI help | Help documentation |
|
||||
| AI plugin | Plugin management |
|
||||
| AI workspace | Workspace configuration |
|
||||
|
||||
### Services
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| AI daemon | Background service management |
|
||||
| AI session | Session recording and replay |
|
||||
| AI lab | Homelab monitoring dashboard |
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
@ -29,3 +71,44 @@ go install forge.lthn.ai/core/cli/cmd/core@latest
|
|||
Verify: `core doctor`
|
||||
|
||||
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
735
docs/environment-variables.md
Normal 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
658
docs/mcp-integration.md
Normal 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
31
mkdocs.yml
|
|
@ -50,19 +50,24 @@ nav:
|
|||
- Workflows: workflows.md
|
||||
- CLI Reference:
|
||||
- Overview: cmd/index.md
|
||||
- AI: cmd/ai/index.md
|
||||
- Build: cmd/build/index.md
|
||||
- CI: cmd/ci/index.md
|
||||
- Dev: cmd/dev/index.md
|
||||
- Go: cmd/go/index.md
|
||||
- PHP: cmd/php/index.md
|
||||
- SDK: cmd/sdk/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
|
||||
- Complete Reference: cli-reference.md
|
||||
- Build Variants: build-variants.md
|
||||
- MCP Integration: mcp-integration.md
|
||||
- Environment Variables: environment-variables.md
|
||||
- Commands:
|
||||
- AI: cmd/ai/index.md
|
||||
- Build: cmd/build/index.md
|
||||
- CI: cmd/ci/index.md
|
||||
- Dev: cmd/dev/index.md
|
||||
- Go: cmd/go/index.md
|
||||
- PHP: cmd/php/index.md
|
||||
- SDK: cmd/sdk/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:
|
||||
- Installation: getting-started/installation.md
|
||||
- Quick Start: getting-started/quickstart.md
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue