lmiranda
a2502c708b
Update all references from old names to new marketplace identity: - support-claude-mktplace → leo-claude-mktplace (URLs) - lm-claude-plugins → leo-claude-mktplace (repo name) - Claude Code Marketplace → Leo Claude Marketplace (display name) Files updated: - Core docs (CLAUDE.md, README.md, CHANGELOG.md) - Documentation (CANONICAL-PATHS, CONFIGURATION, UPDATING, COMMANDS-CHEATSHEET) - Marketplace manifest and all 9 plugin.json files - Plugin READMEs and MCP server READMEs - Setup script and label taxonomy reference Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
381 lines
8.2 KiB
Markdown
381 lines
8.2 KiB
Markdown
# Configuration Guide
|
|
|
|
Centralized configuration documentation for all plugins and MCP servers in the Leo Claude Marketplace.
|
|
|
|
## Overview
|
|
|
|
This marketplace uses a **hybrid configuration** approach:
|
|
- **System-level:** Credentials and service configuration (stored once per machine)
|
|
- **Project-level:** Repository-specific settings (stored per project)
|
|
|
|
**Benefits:**
|
|
- Single token per service (update once, use everywhere)
|
|
- Easy multi-project setup (just add `.env` per project)
|
|
- Security (tokens never committed to git)
|
|
- Project isolation (each project has its own scope)
|
|
|
|
## Prerequisites
|
|
|
|
Before configuring any plugin:
|
|
|
|
1. **Python 3.10+** installed
|
|
```bash
|
|
python3 --version # Should be 3.10.0 or higher
|
|
```
|
|
|
|
2. **Git repository** initialized
|
|
```bash
|
|
git status # Should show initialized repository
|
|
```
|
|
|
|
3. **Claude Code** installed and working
|
|
|
|
---
|
|
|
|
## System-Level Configuration
|
|
|
|
Configuration files stored in `~/.config/claude/`:
|
|
|
|
```bash
|
|
mkdir -p ~/.config/claude
|
|
```
|
|
|
|
### Gitea Configuration
|
|
|
|
Required by: `projman`, `pr-review`
|
|
|
|
```bash
|
|
cat > ~/.config/claude/gitea.env << 'EOF'
|
|
# Gitea API Configuration
|
|
GITEA_URL=https://gitea.example.com
|
|
GITEA_TOKEN=your_gitea_token_here
|
|
GITEA_ORG=your_organization
|
|
EOF
|
|
|
|
# Secure the file
|
|
chmod 600 ~/.config/claude/gitea.env
|
|
```
|
|
|
|
**Variables:**
|
|
| Variable | Description | Example |
|
|
|----------|-------------|---------|
|
|
| `GITEA_URL` | Gitea base URL (no `/api/v1`) | `https://gitea.example.com` |
|
|
| `GITEA_TOKEN` | Personal access token | `glpat-xxx...` |
|
|
| `GITEA_ORG` | Organization name | `bandit` |
|
|
|
|
**Generating Gitea Token:**
|
|
1. Log into Gitea → **User Icon** → **Settings**
|
|
2. **Applications** tab → **Manage Access Tokens**
|
|
3. **Generate New Token** with permissions:
|
|
- `repo` (all sub-permissions)
|
|
- `read:org`
|
|
- `read:user`
|
|
- `write:repo` (for wiki)
|
|
4. Copy token immediately (shown only once)
|
|
|
|
### NetBox Configuration
|
|
|
|
Required by: `cmdb-assistant`
|
|
|
|
```bash
|
|
cat > ~/.config/claude/netbox.env << 'EOF'
|
|
# NetBox API Configuration
|
|
NETBOX_URL=https://netbox.example.com
|
|
NETBOX_TOKEN=your_netbox_token_here
|
|
EOF
|
|
|
|
chmod 600 ~/.config/claude/netbox.env
|
|
```
|
|
|
|
**Variables:**
|
|
| Variable | Description | Example |
|
|
|----------|-------------|---------|
|
|
| `NETBOX_URL` | NetBox base URL | `https://netbox.example.com` |
|
|
| `NETBOX_TOKEN` | API token | `abc123...` |
|
|
|
|
### Git-Flow Configuration
|
|
|
|
Optional system defaults for: `git-flow`
|
|
|
|
```bash
|
|
cat > ~/.config/claude/git-flow.env << 'EOF'
|
|
# Git-Flow Default Configuration
|
|
GIT_WORKFLOW_STYLE=feature-branch
|
|
GIT_DEFAULT_BASE=development
|
|
GIT_AUTO_DELETE_MERGED=true
|
|
GIT_AUTO_PUSH=false
|
|
GIT_PROTECTED_BRANCHES=main,master,development,staging,production
|
|
GIT_COMMIT_STYLE=conventional
|
|
GIT_CO_AUTHOR=true
|
|
EOF
|
|
```
|
|
|
|
---
|
|
|
|
## Project-Level Configuration
|
|
|
|
Create `.env` in each project root:
|
|
|
|
### Gitea Repository (projman, pr-review)
|
|
|
|
```bash
|
|
# .env in project root
|
|
GITEA_REPO=your-repo-name
|
|
```
|
|
|
|
### Git-Flow (project overrides)
|
|
|
|
```bash
|
|
# .env in project root
|
|
GIT_WORKFLOW_STYLE=pr-required
|
|
GIT_DEFAULT_BASE=main
|
|
```
|
|
|
|
### PR Review
|
|
|
|
```bash
|
|
# .env in project root
|
|
PR_REVIEW_CONFIDENCE_THRESHOLD=0.5
|
|
PR_REVIEW_AUTO_SUBMIT=false
|
|
```
|
|
|
|
---
|
|
|
|
## MCP Server Installation
|
|
|
|
MCP servers are located at repository root: `mcp-servers/`
|
|
|
|
### Gitea MCP Server
|
|
|
|
```bash
|
|
cd mcp-servers/gitea
|
|
|
|
# Create virtual environment
|
|
python3 -m venv .venv
|
|
|
|
# Activate
|
|
source .venv/bin/activate
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Verify
|
|
python -c "from mcp_server import server; print('OK')"
|
|
|
|
deactivate
|
|
```
|
|
|
|
### NetBox MCP Server
|
|
|
|
```bash
|
|
cd mcp-servers/netbox
|
|
|
|
# Create virtual environment
|
|
python3 -m venv .venv
|
|
|
|
# Activate
|
|
source .venv/bin/activate
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Verify
|
|
python -c "from mcp_server import server; print('OK')"
|
|
|
|
deactivate
|
|
```
|
|
|
|
---
|
|
|
|
## Plugin Configuration Reference
|
|
|
|
### projman
|
|
|
|
| Level | Variable | Default | Description |
|
|
|-------|----------|---------|-------------|
|
|
| System | `GITEA_URL` | (required) | Gitea API base URL |
|
|
| System | `GITEA_TOKEN` | (required) | API token |
|
|
| System | `GITEA_ORG` | (required) | Organization name |
|
|
| Project | `GITEA_REPO` | (required) | Repository name |
|
|
|
|
**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/review`, `/test-check`, `/test-gen`
|
|
|
|
### pr-review
|
|
|
|
| Level | Variable | Default | Description |
|
|
|-------|----------|---------|-------------|
|
|
| System | `GITEA_URL` | (required) | Gitea API base URL |
|
|
| System | `GITEA_TOKEN` | (required) | API token |
|
|
| Project | `GITEA_REPO` | (required) | Repository name |
|
|
| Project | `PR_REVIEW_CONFIDENCE_THRESHOLD` | `0.5` | Minimum confidence |
|
|
| Project | `PR_REVIEW_AUTO_SUBMIT` | `false` | Auto-submit reviews |
|
|
|
|
**Commands:** `/pr-review`, `/pr-summary`, `/pr-findings`
|
|
|
|
### git-flow
|
|
|
|
| Level | Variable | Default | Description |
|
|
|-------|----------|---------|-------------|
|
|
| System/Project | `GIT_WORKFLOW_STYLE` | `feature-branch` | Branching strategy |
|
|
| System/Project | `GIT_DEFAULT_BASE` | `development` | Default base branch |
|
|
| System/Project | `GIT_AUTO_DELETE_MERGED` | `true` | Delete merged branches |
|
|
| System/Project | `GIT_AUTO_PUSH` | `false` | Auto-push after commit |
|
|
| System/Project | `GIT_PROTECTED_BRANCHES` | `main,master,...` | Protected branches |
|
|
| System/Project | `GIT_COMMIT_STYLE` | `conventional` | Commit message style |
|
|
| System/Project | `GIT_CO_AUTHOR` | `true` | Include Claude co-author |
|
|
|
|
**Commands:** `/commit`, `/commit-push`, `/commit-merge`, `/commit-sync`, `/branch-start`, `/branch-cleanup`, `/git-status`, `/git-config`
|
|
|
|
### clarity-assist
|
|
|
|
No configuration required. Uses sensible defaults.
|
|
|
|
**Commands:** `/clarify`, `/quick-clarify`
|
|
|
|
### cmdb-assistant
|
|
|
|
| Level | Variable | Default | Description |
|
|
|-------|----------|---------|-------------|
|
|
| System | `NETBOX_URL` | (required) | NetBox API base URL |
|
|
| System | `NETBOX_TOKEN` | (required) | API token |
|
|
|
|
### doc-guardian
|
|
|
|
No configuration required. Hook-based plugin.
|
|
|
|
### code-sentinel
|
|
|
|
No configuration required. Hook-based plugin.
|
|
|
|
### project-hygiene
|
|
|
|
No configuration required. Hook-based plugin.
|
|
|
|
### claude-config-maintainer
|
|
|
|
No configuration required.
|
|
|
|
---
|
|
|
|
## Multi-Project Setup
|
|
|
|
1. **System config:** Set up once (credentials)
|
|
2. **Project config:** Create `.env` in each project root
|
|
|
|
**Example:**
|
|
```bash
|
|
# ~/projects/my-app/.env
|
|
GITEA_REPO=my-app
|
|
|
|
# ~/projects/another-app/.env
|
|
GITEA_REPO=another-app
|
|
GIT_WORKFLOW_STYLE=trunk-based
|
|
```
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
### Test Gitea Connection
|
|
|
|
```bash
|
|
curl -H "Authorization: token YOUR_TOKEN" \
|
|
https://gitea.example.com/api/v1/user
|
|
```
|
|
|
|
### Test MCP Server
|
|
|
|
```bash
|
|
cd mcp-servers/gitea
|
|
source .venv/bin/activate
|
|
python -c "from mcp_server import server; print('OK')"
|
|
```
|
|
|
|
### Run Plugin Setup
|
|
|
|
```bash
|
|
# For projman
|
|
/initial-setup
|
|
/labels-sync
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Configuration not found
|
|
|
|
```bash
|
|
# Check system config exists
|
|
ls -la ~/.config/claude/gitea.env
|
|
|
|
# Check permissions (should be 600)
|
|
stat ~/.config/claude/gitea.env
|
|
```
|
|
|
|
### Authentication failed
|
|
|
|
```bash
|
|
# Test token directly
|
|
curl -H "Authorization: token YOUR_TOKEN" \
|
|
https://gitea.example.com/api/v1/user
|
|
|
|
# Regenerate if invalid
|
|
```
|
|
|
|
### MCP server not starting
|
|
|
|
```bash
|
|
# Check venv exists
|
|
ls mcp-servers/gitea/.venv
|
|
|
|
# Reinstall if missing
|
|
cd mcp-servers/gitea
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Wrong repository
|
|
|
|
```bash
|
|
# Check project .env
|
|
cat .env
|
|
|
|
# Verify GITEA_REPO matches exactly
|
|
```
|
|
|
|
---
|
|
|
|
## Security Best Practices
|
|
|
|
1. **Never commit tokens**
|
|
- Keep credentials in `~/.config/claude/` only
|
|
- Add `.env` to `.gitignore`
|
|
|
|
2. **Secure configuration files**
|
|
```bash
|
|
chmod 600 ~/.config/claude/*.env
|
|
```
|
|
|
|
3. **Rotate tokens periodically**
|
|
- Every 6-12 months
|
|
- Immediately if compromised
|
|
|
|
4. **Minimum permissions**
|
|
- Only grant required token permissions
|
|
- Use separate tokens for different environments
|
|
|
|
---
|
|
|
|
## Quick Setup Checklist
|
|
|
|
- [ ] Python 3.10+ installed
|
|
- [ ] `~/.config/claude/` directory created
|
|
- [ ] Service credentials configured (gitea.env, netbox.env)
|
|
- [ ] Configuration files secured (chmod 600)
|
|
- [ ] MCP servers installed with venv
|
|
- [ ] Project `.env` created with repository settings
|
|
- [ ] Connections tested
|
|
- [ ] Plugin commands verified
|