feat: v3.0.0 architecture overhaul
- Rename marketplace to lm-claude-plugins - Move MCP servers to root with symlinks - Add 6 PR tools to Gitea MCP (list_pull_requests, get_pull_request, get_pr_diff, get_pr_comments, create_pr_review, add_pr_comment) - Add clarity-assist plugin (prompt optimization with ND accommodations) - Add git-flow plugin (workflow automation) - Add pr-review plugin (multi-agent review with confidence scoring) - Centralize configuration docs - Update all documentation for v3.0.0 BREAKING CHANGE: MCP server paths changed, marketplace renamed Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -2,64 +2,106 @@
|
||||
|
||||
**This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
|
||||
|
||||
Last Updated: 2026-01-20
|
||||
Last Updated: 2026-01-20 (v3.0.0)
|
||||
|
||||
---
|
||||
|
||||
## Repository Root Structure
|
||||
|
||||
```
|
||||
support-claude-mktplace/
|
||||
lm-claude-plugins/
|
||||
├── .claude/ # Claude Code local settings
|
||||
├── .claude-plugin/ # Marketplace manifest (claude-code-marketplace)
|
||||
├── .claude-plugin/ # Marketplace manifest
|
||||
│ └── marketplace.json
|
||||
├── .scratch/ # Transient work (auto-cleaned)
|
||||
├── docs/ # All documentation
|
||||
│ ├── architecture/ # Draw.io diagrams and specs
|
||||
│ ├── CANONICAL-PATHS.md # This file - single source of truth
|
||||
│ ├── CONFIGURATION.md # Centralized configuration guide
|
||||
│ ├── UPDATING.md # Update guide
|
||||
│ └── workflows/ # Workflow documentation
|
||||
├── hooks/ # Shared hooks (if any)
|
||||
├── plugins/ # ALL plugins with bundled MCP servers
|
||||
│ ├── projman/
|
||||
├── mcp-servers/ # SHARED MCP servers (v3.0.0+)
|
||||
│ ├── gitea/ # Gitea MCP server
|
||||
│ │ ├── mcp_server/
|
||||
│ │ │ ├── server.py
|
||||
│ │ │ ├── gitea_client.py
|
||||
│ │ │ ├── config.py
|
||||
│ │ │ └── tools/
|
||||
│ │ │ ├── issues.py
|
||||
│ │ │ ├── labels.py
|
||||
│ │ │ ├── wiki.py
|
||||
│ │ │ ├── milestones.py
|
||||
│ │ │ ├── dependencies.py
|
||||
│ │ │ └── pull_requests.py # NEW in v3.0.0
|
||||
│ │ ├── requirements.txt
|
||||
│ │ └── .venv/
|
||||
│ └── netbox/ # NetBox MCP server
|
||||
│ ├── mcp_server/
|
||||
│ ├── requirements.txt
|
||||
│ └── .venv/
|
||||
├── plugins/ # ALL plugins
|
||||
│ ├── projman/ # Sprint management
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── mcp-servers/ # MCP servers bundled IN plugin
|
||||
│ │ │ └── gitea/ # Gitea + Wiki tools
|
||||
│ │ ├── .mcp.json
|
||||
│ │ ├── mcp-servers/
|
||||
│ │ │ └── gitea -> ../../../mcp-servers/gitea # SYMLINK
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md # CLAUDE.md integration snippet
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── doc-guardian/ # Documentation drift detection
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── hooks/ # PostToolUse, Stop hooks
|
||||
│ │ ├── hooks/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── code-sentinel/ # Security scanning & refactoring
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── hooks/ # PreToolUse hook
|
||||
│ │ ├── hooks/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── projman-pmo/
|
||||
│ ├── cmdb-assistant/
|
||||
│ ├── cmdb-assistant/ # NetBox CMDB integration
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── mcp-servers/ # MCP servers bundled IN plugin
|
||||
│ │ │ └── netbox/
|
||||
│ │ ├── .mcp.json
|
||||
│ │ ├── mcp-servers/
|
||||
│ │ │ └── netbox -> ../../../mcp-servers/netbox # SYMLINK
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ └── claude-md-integration.md # CLAUDE.md integration snippet
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── claude-config-maintainer/
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ └── claude-md-integration.md # CLAUDE.md integration snippet
|
||||
│ └── project-hygiene/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── project-hygiene/
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── hooks/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── clarity-assist/ # NEW in v3.0.0
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── git-flow/ # NEW in v3.0.0
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ └── pr-review/ # NEW in v3.0.0
|
||||
│ ├── .claude-plugin/
|
||||
│ ├── hooks/
|
||||
│ └── claude-md-integration.md # CLAUDE.md integration snippet
|
||||
│ ├── .mcp.json
|
||||
│ ├── mcp-servers/
|
||||
│ │ └── gitea -> ../../../mcp-servers/gitea # SYMLINK
|
||||
│ ├── commands/
|
||||
│ ├── agents/
|
||||
│ ├── skills/
|
||||
│ └── claude-md-integration.md
|
||||
├── scripts/ # Setup and maintenance scripts
|
||||
├── CLAUDE.md
|
||||
├── README.md
|
||||
@@ -83,22 +125,26 @@ support-claude-mktplace/
|
||||
| Plugin .mcp.json | `plugins/{plugin-name}/.mcp.json` | `plugins/projman/.mcp.json` |
|
||||
| Plugin integration snippet | `plugins/{plugin-name}/claude-md-integration.md` | `plugins/projman/claude-md-integration.md` |
|
||||
|
||||
### MCP Server Paths (Bundled in Plugins)
|
||||
### MCP Server Paths (v3.0.0 Architecture)
|
||||
|
||||
MCP servers are now **bundled inside each plugin** to ensure they work when plugins are cached.
|
||||
MCP servers are **shared at repository root** with **symlinks** from plugins.
|
||||
|
||||
| Context | Pattern | Example |
|
||||
|---------|---------|---------|
|
||||
| MCP server location | `plugins/{plugin}/mcp-servers/{server}/` | `plugins/projman/mcp-servers/gitea/` |
|
||||
| MCP server code | `plugins/{plugin}/mcp-servers/{server}/mcp_server/` | `plugins/projman/mcp-servers/gitea/mcp_server/` |
|
||||
| MCP venv | `plugins/{plugin}/mcp-servers/{server}/.venv/` | `plugins/projman/mcp-servers/gitea/.venv/` |
|
||||
| Shared MCP server | `mcp-servers/{server}/` | `mcp-servers/gitea/` |
|
||||
| MCP server code | `mcp-servers/{server}/mcp_server/` | `mcp-servers/gitea/mcp_server/` |
|
||||
| MCP venv | `mcp-servers/{server}/.venv/` | `mcp-servers/gitea/.venv/` |
|
||||
| Plugin symlink | `plugins/{plugin}/mcp-servers/{server}` | `plugins/projman/mcp-servers/gitea` |
|
||||
|
||||
### Relative Path Patterns (CRITICAL)
|
||||
### Symlink Pattern
|
||||
|
||||
| From | To | Pattern |
|
||||
|------|----|---------|
|
||||
| Plugin .mcp.json | Bundled MCP server | `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{server}` |
|
||||
| marketplace.json | Plugin | `./plugins/{plugin-name}` |
|
||||
Plugins that use MCP servers create symlinks:
|
||||
```bash
|
||||
# From plugin directory
|
||||
ln -s ../../../mcp-servers/gitea plugins/projman/mcp-servers/gitea
|
||||
```
|
||||
|
||||
The symlink target is relative: `../../../mcp-servers/{server}`
|
||||
|
||||
### Documentation Paths
|
||||
|
||||
@@ -108,6 +154,7 @@ MCP servers are now **bundled inside each plugin** to ensure they work when plug
|
||||
| Workflow docs | `docs/workflows/` |
|
||||
| This file | `docs/CANONICAL-PATHS.md` |
|
||||
| Update guide | `docs/UPDATING.md` |
|
||||
| Configuration guide | `docs/CONFIGURATION.md` |
|
||||
|
||||
---
|
||||
|
||||
@@ -125,15 +172,15 @@ MCP servers are now **bundled inside each plugin** to ensure they work when plug
|
||||
2. Verify each path against patterns in this file
|
||||
3. Show verification to user before proceeding
|
||||
|
||||
### Relative Path Calculation
|
||||
### Relative Path Calculation (v3.0.0)
|
||||
|
||||
From `plugins/projman/.mcp.json` to bundled `mcp-servers/gitea/`:
|
||||
From `plugins/projman/.mcp.json` to shared `mcp-servers/gitea/`:
|
||||
```
|
||||
plugins/projman/.mcp.json
|
||||
→ MCP servers are IN the plugin at mcp-servers/
|
||||
→ Uses ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/
|
||||
→ Symlink at plugins/projman/mcp-servers/gitea points to ../../../mcp-servers/gitea
|
||||
|
||||
Result: mcp-servers/gitea/
|
||||
With variable: ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/
|
||||
Result in .mcp.json: ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/.venv/bin/python
|
||||
```
|
||||
|
||||
From `.claude-plugin/marketplace.json` to `plugins/projman/`:
|
||||
@@ -152,18 +199,28 @@ Result: ./plugins/projman
|
||||
| Wrong | Why | Correct |
|
||||
|-------|-----|---------|
|
||||
| `projman/` at root | Plugins go in `plugins/` | `plugins/projman/` |
|
||||
| `mcp-servers/` at root | MCP servers are bundled in plugins | `plugins/{plugin}/mcp-servers/` |
|
||||
| `../../mcp-servers/` from plugin | Old pattern, doesn't work with caching | `${CLAUDE_PLUGIN_ROOT}/mcp-servers/` |
|
||||
| `./../../../plugins/projman` in marketplace | Wrong (old nested structure) | `./plugins/projman` |
|
||||
| Direct path in .mcp.json to root mcp-servers | Use symlink | Symlink at `plugins/{plugin}/mcp-servers/` |
|
||||
| Creating new mcp-servers inside plugins | Use shared + symlink | Symlink to `mcp-servers/` |
|
||||
| Hardcoding absolute paths | Breaks portability | Use `${CLAUDE_PLUGIN_ROOT}` |
|
||||
|
||||
---
|
||||
|
||||
## Architecture Note
|
||||
## Architecture Note (v3.0.0)
|
||||
|
||||
MCP servers are bundled inside each plugin (not shared at root) because:
|
||||
- Claude Code caches only the plugin directory when installed
|
||||
- Relative paths to parent directories break in the cache
|
||||
- Each plugin must be self-contained to work properly
|
||||
MCP servers are now **shared at repository root** with **symlinks** from plugins:
|
||||
|
||||
**Benefits:**
|
||||
- Single source of truth for each MCP server
|
||||
- Updates apply to all plugins automatically
|
||||
- Reduced duplication
|
||||
- Symlinks work with Claude Code caching
|
||||
|
||||
**Symlink Pattern:**
|
||||
```
|
||||
plugins/projman/mcp-servers/gitea -> ../../../mcp-servers/gitea
|
||||
plugins/cmdb-assistant/mcp-servers/netbox -> ../../../mcp-servers/netbox
|
||||
plugins/pr-review/mcp-servers/gitea -> ../../../mcp-servers/gitea
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -171,7 +228,11 @@ MCP servers are bundled inside each plugin (not shared at root) because:
|
||||
|
||||
| Date | Change | By |
|
||||
|------|--------|-----|
|
||||
| 2026-01-20 | v3.0.0: MCP servers moved to root with symlinks | Claude Code |
|
||||
| 2026-01-20 | v3.0.0: Added clarity-assist, git-flow, pr-review plugins | Claude Code |
|
||||
| 2026-01-20 | v3.0.0: Added docs/CONFIGURATION.md | Claude Code |
|
||||
| 2026-01-20 | v3.0.0: Renamed marketplace to lm-claude-plugins | Claude Code |
|
||||
| 2026-01-20 | Removed docs/references/ (obsolete planning docs) | Claude Code |
|
||||
| 2026-01-19 | Added claude-md-integration.md path pattern for plugin integration snippets | Claude Code |
|
||||
| 2025-12-15 | Restructured: MCP servers now bundled in plugins | Claude Code |
|
||||
| 2026-01-19 | Added claude-md-integration.md path pattern | Claude Code |
|
||||
| 2025-12-15 | Restructured: MCP servers bundled in plugins | Claude Code |
|
||||
| 2025-12-12 | Initial creation | Claude Code |
|
||||
|
||||
380
docs/CONFIGURATION.md
Normal file
380
docs/CONFIGURATION.md
Normal file
@@ -0,0 +1,380 @@
|
||||
# Configuration Guide
|
||||
|
||||
Centralized configuration documentation for all plugins and MCP servers in the lm-claude-plugins 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
|
||||
Reference in New Issue
Block a user