leo-claude-mktplace/docs/CONFIGURATION.md

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

   python3 --version  # Should be 3.10.0 or higher
   

2. Git repository initialized

   git status  # Should show initialized repository
   

3. Claude Code installed and working

---

System-Level Configuration

Configuration files stored in ~/.config/claude/:

mkdir -p ~/.config/claude

Gitea Configuration

Required by: projman, pr-review

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

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

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)

# .env in project root
GITEA_REPO=your-repo-name

Git-Flow (project overrides)

# .env in project root
GIT_WORKFLOW_STYLE=pr-required
GIT_DEFAULT_BASE=main

PR Review

# .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

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

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:

# ~/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

curl -H "Authorization: token YOUR_TOKEN" \
  https://gitea.example.com/api/v1/user

Test MCP Server

cd mcp-servers/gitea
source .venv/bin/activate
python -c "from mcp_server import server; print('OK')"

Run Plugin Setup

# For projman
/initial-setup
/labels-sync

---

Troubleshooting

Configuration not found

# Check system config exists
ls -la ~/.config/claude/gitea.env

# Check permissions (should be 600)
stat ~/.config/claude/gitea.env

Authentication failed

# Test token directly
curl -H "Authorization: token YOUR_TOKEN" \
  https://gitea.example.com/api/v1/user

# Regenerate if invalid

MCP server not starting

# 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

# 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

   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