personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update CONFIGURATION.md for v1.0.0

Browse Source 
- Remove Wiki.js configuration (replaced by Gitea Wiki)
- Update MCP server paths (bundled in plugin)
- Update token permissions for wiki access
- Simplify setup steps

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-01-19 17:17:30 -05:00
parent 657b7a7a6f
commit ee33f63c9c
1 changed files with 107 additions and 208 deletions
Download Patch File Download Diff File Expand all files Collapse all files

315
plugins/projman/CONFIGURATION.md
View File

@@ -1,18 +1,18 @@
# Configuration Guide - Projman Plugin # Configuration Guide - Projman Plugin v1.0.0
Complete setup and configuration instructions for the Projman project management plugin. Complete setup and configuration instructions for the Projman project management plugin.
## Overview ## Overview
The Projman plugin uses a **hybrid configuration** approach: The Projman plugin uses a **hybrid configuration** approach:
- **System-level:** Credentials for Gitea and Wiki.js (stored once per machine) - **System-level:** Credentials for Gitea (stored once per machine)
- **Project-level:** Repository and project paths (stored per project) - **Project-level:** Repository path (stored per project)
This design allows: This design allows:
- ✅ Single token per service (update once, use everywhere) - Single token per service (update once, use everywhere)
- ✅ Easy multi-project setup (just add `.env` per project) - Easy multi-project setup (just add `.env` per project)
- ✅ Security (tokens never committed to git) - Security (tokens never committed to git)
- ✅ Project isolation (each project has its own scope) - Project isolation (each project has its own scope)
## Prerequisites ## Prerequisites
@@ -20,7 +20,7 @@ Before configuring the plugin, ensure you have:
1. **Python 3.10+** installed 1. **Python 3.10+** installed
```bash ```bash
python --version # Should be 3.10.0 or higher python3 --version # Should be 3.10.0 or higher
``` ```
2. **Git repository** initialized 2. **Git repository** initialized
@@ -32,26 +32,20 @@ Before configuring the plugin, ensure you have:
- Create issues - Create issues
- Manage labels - Manage labels
- Read organization information - Read organization information
- Access repository wiki
4. **Wiki.js access** with an account and permissions to: 4. **Claude Code** installed and working
- Create and edit pages
- Manage tags
- Read and write content
5. **Claude Code** installed and working ## Step 1: Install MCP Server
## Step 1: Install MCP Servers The plugin bundles the Gitea MCP server at `mcp-servers/gitea/`:
The plugin requires two MCP servers installed at `../mcp-servers/` relative to the plugin:
### 1.1 Install Gitea MCP Server
```bash ```bash
# Navigate to Gitea MCP server directory # Navigate to MCP server directory (inside plugin)
cd ../mcp-servers/gitea cd plugins/projman/mcp-servers/gitea
# Create virtual environment # Create virtual environment
python -m venv .venv python3 -m venv .venv
# Activate virtual environment # Activate virtual environment
source .venv/bin/activate # Linux/Mac source .venv/bin/activate # Linux/Mac
@@ -63,32 +57,12 @@ pip install -r requirements.txt
# Verify installation # Verify installation
python -c "from mcp_server import server; print('Gitea MCP Server installed successfully')" python -c "from mcp_server import server; print('Gitea MCP Server installed successfully')"
# Deactivate when done
deactivate
``` ```
### 1.2 Install Wiki.js MCP Server ## Step 2: Generate Gitea API Token
```bash
# Navigate to Wiki.js MCP server directory
cd ../mcp-servers/wikijs
# Create virtual environment
python -m venv .venv
# Activate virtual environment
source .venv/bin/activate # Linux/Mac
# or
.venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Verify installation
python -c "from mcp_server import server; print('Wiki.js MCP Server installed successfully')"
```
## Step 2: Generate API Tokens
### 2.1 Generate Gitea API Token
1. Log into Gitea: https://gitea.example.com 1. Log into Gitea: https://gitea.example.com
2. Navigate to: **User Icon** (top right) → **Settings** 2. Navigate to: **User Icon** (top right) → **Settings**
@@ -98,41 +72,23 @@ python -c "from mcp_server import server; print('Wiki.js MCP Server installed su
6. Configure token: 6. Configure token:
- **Token Name:** `claude-code-projman` - **Token Name:** `claude-code-projman`
- **Permissions:** - **Permissions:**
- ✅ `repo` (all sub-permissions) - Repository access - `repo` (all sub-permissions) - Repository access
- ✅ `read:org` - Read organization information and labels - `read:org` - Read organization information and labels
- ✅ `read:user` - Read user information - `read:user` - Read user information
- `write:repo` - Wiki access
7. Click **Generate Token** 7. Click **Generate Token**
8. **IMPORTANT:** Copy token immediately (shown only once!) 8. **IMPORTANT:** Copy token immediately (shown only once!)
9. Save token securely - you'll need it in Step 3 9. Save token securely - you'll need it in Step 3
**Token Permissions Explained:** **Token Permissions Explained:**
- `repo` - Create, read, update issues and labels - `repo` - Create, read, update issues, labels, and wiki
- `read:org` - Access organization-level labels - `read:org` - Access organization-level labels
- `read:user` - Associate issues with user account - `read:user` - Associate issues with user account
- `write:repo` - Create wiki pages for lessons learned
### 2.2 Generate Wiki.js API Token
1. Log into Wiki.js: https://wiki.your-company.com
2. Navigate to: **Administration** (top right)
3. Click **API Access** in the left sidebar
4. Click **New API Key**
5. Configure API key:
- **Name:** `claude-code-projman`
- **Expiration:** None (or set to your security policy)
- **Permissions:**
- ✅ **Pages:** Read, Create, Update
- ✅ **Search:** Read
6. Click **Create**
7. **IMPORTANT:** Copy the JWT token immediately (shown only once!)
8. Save token securely - you'll need it in Step 3
**Token Permissions Explained:**
- Pages (read/create/update) - Manage documentation and lessons learned
- Search (read) - Find relevant lessons from previous sprints
## Step 3: System-Level Configuration ## Step 3: System-Level Configuration
Create system-wide configuration files in `~/.config/claude/`: Create system-wide configuration file in `~/.config/claude/`:
### 3.1 Create Configuration Directory ### 3.1 Create Configuration Directory
@@ -145,55 +101,35 @@ mkdir -p ~/.config/claude
```bash ```bash
cat > ~/.config/claude/gitea.env << 'EOF' cat > ~/.config/claude/gitea.env << 'EOF'
# Gitea API Configuration # Gitea API Configuration
GITEA_API_URL=https://gitea.example.com/api/v1 GITEA_URL=https://gitea.example.com
GITEA_API_TOKEN=your_gitea_token_here GITEA_TOKEN=your_gitea_token_here
GITEA_OWNER=bandit GITEA_ORG=your_organization
EOF EOF
# Secure the file (owner read/write only) # Secure the file (owner read/write only)
chmod 600 ~/.config/claude/gitea.env chmod 600 ~/.config/claude/gitea.env
``` ```
**Replace `your_gitea_token_here` with the token from Step 2.1** **Replace placeholders:**
- `your_gitea_token_here` with the token from Step 2
- `your_organization` with your Gitea organization name
**Configuration Variables:** **Configuration Variables:**
- `GITEA_API_URL` - Gitea API endpoint (includes `/api/v1`) - `GITEA_URL` - Gitea base URL (without `/api/v1`)
- `GITEA_API_TOKEN` - Personal access token from Step 2.1 - `GITEA_TOKEN` - Personal access token from Step 2
- `GITEA_OWNER` - Organization or user name (e.g., `bandit`) - `GITEA_ORG` - Organization name (e.g., `bandit`)
### 3.3 Configure Wiki.js ### 3.3 Verify System Configuration
```bash ```bash
cat > ~/.config/claude/wikijs.env << 'EOF' # Check file exists and has correct permissions
# Wiki.js API Configuration ls -la ~/.config/claude/gitea.env
WIKIJS_API_URL=https://wiki.your-company.com/graphql
WIKIJS_API_TOKEN=your_wikijs_token_here
WIKIJS_BASE_PATH=/your-org
EOF
# Secure the file (owner read/write only)
chmod 600 ~/.config/claude/wikijs.env
```
**Replace `your_wikijs_token_here` with the JWT token from Step 2.2**
**Configuration Variables:**
- `WIKIJS_API_URL` - Wiki.js GraphQL endpoint (includes `/graphql`)
- `WIKIJS_API_TOKEN` - API key from Step 2.2 (JWT format)
- `WIKIJS_BASE_PATH` - Base path in Wiki.js (e.g., `/your-org`)
### 3.4 Verify System Configuration
```bash
# Check files exist and have correct permissions
ls -la ~/.config/claude/
# Should show: # Should show:
# -rw------- gitea.env # -rw------- gitea.env
# -rw------- wikijs.env
``` ```
**Security Note:** Files should have `600` permissions (owner read/write only) to protect API tokens. **Security Note:** File should have `600` permissions (owner read/write only) to protect API tokens.
## Step 4: Project-Level Configuration ## Step 4: Project-Level Configuration
@@ -206,42 +142,28 @@ For each project where you'll use Projman, create a `.env` file:
cat > .env << 'EOF' cat > .env << 'EOF'
# Gitea Repository Configuration # Gitea Repository Configuration
GITEA_REPO=your-repo-name GITEA_REPO=your-repo-name
# Wiki.js Project Configuration
WIKIJS_PROJECT=projects/your-project-name
EOF EOF
``` ```
**Example for CuisineFlow project:** **Example for MyProject:**
```bash ```bash
cat > .env << 'EOF' cat > .env << 'EOF'
GITEA_REPO=cuisineflow GITEA_REPO=my-project
WIKIJS_PROJECT=projects/cuisineflow
EOF EOF
``` ```
### 4.2 Add .env to .gitignore ### 4.2 Verify Project Configuration
**CRITICAL:** Never commit `.env` to git!
```bash
# Add to .gitignore
echo ".env" >> .gitignore
# Verify
git check-ignore .env # Should output: .env
```
### 4.3 Verify Project Configuration
```bash ```bash
# Check .env exists # Check .env exists
ls -la .env ls -la .env
# Check it's in .gitignore # Check .env content
cat .gitignore | grep "\.env" cat .env
``` ```
**Note:** The `.env` file may already be in your `.gitignore`. If your project uses `.env` for other purposes, the Gitea configuration will merge with existing variables.
## Step 5: Configuration Verification ## Step 5: Configuration Verification
Test that everything is configured correctly: Test that everything is configured correctly:
@@ -256,23 +178,21 @@ curl -H "Authorization: token YOUR_GITEA_TOKEN" \
# Should return your user information in JSON format # Should return your user information in JSON format
``` ```
### 5.2 Test Wiki.js Connection ### 5.2 Test Wiki Access
```bash ```bash
# Test GraphQL endpoint # Test wiki API
curl -H "Authorization: Bearer YOUR_WIKIJS_TOKEN" \ curl -H "Authorization: token YOUR_GITEA_TOKEN" \
-H "Content-Type: application/json" \ https://gitea.example.com/api/v1/repos/YOUR_ORG/YOUR_REPO/wiki/pages
-d '{"query": "{ pages { list { id title } } }"}' \
https://wiki.your-company.com/graphql
# Should return pages data in JSON format # Should return list of wiki pages (or empty array)
``` ```
### 5.3 Test MCP Server Loading ### 5.3 Test MCP Server Loading
```bash ```bash
# Navigate to plugin directory # Navigate to plugin directory
cd projman cd plugins/projman
# Verify .mcp.json exists # Verify .mcp.json exists
cat .mcp.json cat .mcp.json
@@ -283,9 +203,19 @@ claude --debug
## Step 6: Initialize Plugin ## Step 6: Initialize Plugin
### 6.1 Sync Label Taxonomy ### 6.1 Run Initial Setup
First time setup - fetch labels from Gitea: ```bash
/initial-setup
```
This will:
- Validate Gitea MCP server connection
- Test credential configuration
- Sync label taxonomy
- Verify required directory structure
### 6.2 Sync Label Taxonomy
```bash ```bash
/labels-sync /labels-sync
@@ -296,15 +226,16 @@ This will:
- Update `skills/label-taxonomy/labels-reference.md` - Update `skills/label-taxonomy/labels-reference.md`
- Enable intelligent label suggestions - Enable intelligent label suggestions
### 6.2 Verify Commands Available ### 6.3 Verify Commands Available
```bash ```bash
# List available commands # List available commands
/sprint-plan --help /sprint-plan
/sprint-start --help /sprint-start
/sprint-status --help /sprint-status
/sprint-close --help /sprint-close
/labels-sync --help /labels-sync
/initial-setup
``` ```
## Configuration Files Reference ## Configuration Files Reference
@@ -313,16 +244,9 @@ This will:
**`~/.config/claude/gitea.env`:** **`~/.config/claude/gitea.env`:**
```bash ```bash
GITEA_API_URL=https://gitea.example.com/api/v1 GITEA_URL=https://gitea.example.com
GITEA_API_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxxx GITEA_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxxx
GITEA_OWNER=bandit GITEA_ORG=your_organization
```
**`~/.config/claude/wikijs.env`:**
```bash
WIKIJS_API_URL=https://wiki.your-company.com/graphql
WIKIJS_API_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
WIKIJS_BASE_PATH=/your-org
``` ```
### Project-Level Files ### Project-Level Files
@@ -330,12 +254,6 @@ WIKIJS_BASE_PATH=/your-org
**`.env` (in project root):** **`.env` (in project root):**
```bash ```bash
GITEA_REPO=your-repo-name GITEA_REPO=your-repo-name
WIKIJS_PROJECT=projects/your-project-name
```
**`.gitignore` (must include):**
```
.env
``` ```
### Plugin Configuration ### Plugin Configuration
@@ -345,19 +263,11 @@ WIKIJS_PROJECT=projects/your-project-name
{ {
"mcpServers": { "mcpServers": {
"gitea": { "gitea": {
"command": "python", "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/.venv/bin/python",
"args": ["-m", "mcp_server.server"], "args": ["-m", "mcp_server.server"],
"cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", "cwd": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea",
"env": { "env": {
"PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea" "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea"
}
},
"wikijs": {
"command": "python",
"args": ["-m", "mcp_server.server"],
"cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs",
"env": {
"PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs"
} }
} }
} }
@@ -375,24 +285,21 @@ To use Projman with multiple projects:
```bash ```bash
# ~/projects/my-app/.env # ~/projects/my-app/.env
GITEA_REPO=my-app GITEA_REPO=my-app
WIKIJS_PROJECT=projects/my-app
``` ```
**Project 2: App Site** **Project 2: App Site**
```bash ```bash
# ~/projects/my-app-site/.env # ~/projects/my-app-site/.env
GITEA_REPO=my-app-site GITEA_REPO=my-app-site
WIKIJS_PROJECT=projects/my-app-site
``` ```
**Project 3: Company Site** **Project 3: Company Site**
```bash ```bash
# ~/projects/company-site/.env # ~/projects/company-site/.env
GITEA_REPO=company-site GITEA_REPO=company-site
WIKIJS_PROJECT=projects/company-site
``` ```
Each project operates independently with its own issues and lessons learned. Each project operates independently with its own issues and lessons learned (stored in each repository's wiki).
## Troubleshooting ## Troubleshooting
@@ -404,7 +311,6 @@ Each project operates independently with its own issues and lessons learned.
```bash ```bash
# Check system config exists # Check system config exists
ls -la ~/.config/claude/gitea.env ls -la ~/.config/claude/gitea.env
ls -la ~/.config/claude/wikijs.env
# If missing, recreate from Step 3 # If missing, recreate from Step 3
``` ```
@@ -419,10 +325,6 @@ ls -la ~/.config/claude/wikijs.env
curl -H "Authorization: token YOUR_TOKEN" \ curl -H "Authorization: token YOUR_TOKEN" \
https://gitea.example.com/api/v1/user https://gitea.example.com/api/v1/user
# Test Wiki.js token
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://wiki.your-company.com/graphql
# If fails, regenerate token (Step 2) # If fails, regenerate token (Step 2)
``` ```
@@ -433,13 +335,12 @@ curl -H "Authorization: Bearer YOUR_TOKEN" \
**Solution:** **Solution:**
```bash ```bash
# Check Python virtual environment exists # Check Python virtual environment exists
ls ../mcp-servers/gitea/.venv ls plugins/projman/mcp-servers/gitea/.venv
ls ../mcp-servers/wikijs/.venv
# If missing, reinstall (Step 1) # If missing, reinstall (Step 1)
# Check dependencies installed # Check dependencies installed
cd ../mcp-servers/gitea cd plugins/projman/mcp-servers/gitea
source .venv/bin/activate source .venv/bin/activate
python -c "import requests; import mcp" python -c "import requests; import mcp"
@@ -447,35 +348,41 @@ python -c "import requests; import mcp"
pip install -r requirements.txt pip install -r requirements.txt
``` ```
### Wrong repository or project ### Wrong repository
**Problem:** Issues created in wrong repo or lessons saved to wrong project **Problem:** Issues created in wrong repo
**Solution:** **Solution:**
```bash ```bash
# Check project .env configuration # Check project .env configuration
cat .env cat .env
# Verify GITEA_REPO matches Gitea repository name # Verify GITEA_REPO matches Gitea repository name exactly
# Verify WIKIJS_PROJECT matches Wiki.js project path
# Update if incorrect # Update if incorrect
nano .env
``` ```
### Permissions errors ### Permissions errors
**Problem:** "Permission denied" when creating issues or pages **Problem:** "Permission denied" when creating issues or wiki pages
**Solution:** **Solution:**
- **Gitea:** Verify token has `repo` and `read:org` permissions (Step 2.1) - Verify token has `repo`, `read:org`, and `write:repo` permissions (Step 2)
- **Wiki.js:** Verify token has Pages (create/update) permissions (Step 2.2) - Regenerate token with correct permissions if needed
- Regenerate tokens with correct permissions if needed
### Repository not in organization
**Problem:** "Repository must belong to configured organization"
**Solution:**
- Verify `GITEA_ORG` in system config matches the organization owning the repository
- Verify `GITEA_REPO` belongs to that organization
- Fork the repository to your organization if needed
## Security Best Practices ## Security Best Practices
1. **Never commit tokens** 1. **Never commit tokens**
- Keep `.env` in `.gitignore` - Keep credentials in `~/.config/claude/` only
- Never hardcode tokens in code - Never hardcode tokens in code
- Use system-level config for credentials - Use system-level config for credentials
@@ -491,51 +398,43 @@ nano .env
4. **Minimum permissions** 4. **Minimum permissions**
- Only grant required permissions - Only grant required permissions
- Gitea: `repo`, `read:org`, `read:user` - Gitea: `repo`, `read:org`, `read:user`, `write:repo`
- Wiki.js: Pages (read/create/update), Search (read)
5. **Monitor usage** 5. **Monitor usage**
- Review Gitea access logs periodically - Review Gitea access logs periodically
- Check Wiki.js audit logs
- Watch for unexpected API usage - Watch for unexpected API usage
## Next Steps ## Next Steps
After configuration is complete: After configuration is complete:
1. ✅ Run `/labels-sync` to fetch label taxonomy 1. Run `/initial-setup` to verify everything works
2. ✅ Try `/sprint-plan` to start your first sprint 2. Run `/labels-sync` to fetch label taxonomy
3. ✅ Read [README.md](./README.md) for usage guide 3. Try `/sprint-plan` to start your first sprint
4. ✅ Review command documentation in `commands/` 4. Read [README.md](./README.md) for usage guide
## Support ## Support
**Configuration Issues:** **Configuration Issues:**
- Check [README.md](./README.md) troubleshooting section - Check [README.md](./README.md) troubleshooting section
- Review MCP server documentation:
- [Gitea MCP](../mcp-servers/gitea/README.md)
- [Wiki.js MCP](../mcp-servers/wikijs/README.md)
- Contact repository maintainer for support - Contact repository maintainer for support
**Questions:** **Questions:**
- Read command documentation: `commands/*.md` - Read command documentation: `commands/*.md`
- Check agent descriptions in `agents/` (Phase 3) - Check agent descriptions in `agents/`
- Review skills: `skills/label-taxonomy/`
--- ---
**Configuration Status Checklist:** **Configuration Status Checklist:**
- [ ] Python 3.10+ installed - [ ] Python 3.10+ installed
- [ ] Gitea MCP server installed - [ ] Gitea MCP server installed (in `mcp-servers/gitea/`)
- [ ] Wiki.js MCP server installed - [ ] Gitea API token generated with correct permissions
- [ ] Gitea API token generated - [ ] System config created (`~/.config/claude/gitea.env`)
- [ ] Wiki.js API token generated
- [ ] System config created (`~/.config/claude/*.env`)
- [ ] Project config created (`.env`) - [ ] Project config created (`.env`)
- [ ] `.env` added to `.gitignore`
- [ ] Gitea connection tested - [ ] Gitea connection tested
- [ ] Wiki.js connection tested - [ ] Wiki access tested
- [ ] `/initial-setup` completed successfully
- [ ] `/labels-sync` completed successfully - [ ] `/labels-sync` completed successfully
- [ ] Commands verified available - [ ] Commands verified available