diff --git a/MCP-SETUP.md b/MCP-SETUP.md new file mode 100644 index 0000000..05508db --- /dev/null +++ b/MCP-SETUP.md @@ -0,0 +1,221 @@ +# MCP Server Setup Guide + +## What is MCP? + +Model Context Protocol (MCP) is a standard for connecting AI assistants like Claude to external tools and data sources. Your cluster has MCP servers that provide programmatic access to services like Gitea. + +## MCP Servers in Your Cluster + +Currently running MCP servers: + +```bash +kubectl get svc -n mcp +``` + +- **mcp-ecosystem-gitea-mcp** (10.43.80.98:3014) +- **mcp-umbrella-gitea-mcp** (10.43.241.50:3014) + +## How to Connect MCP to Claude Code + +To make MCP tools available in Claude Code sessions, you need to configure the MCP server connection in your Claude Code settings. + +### Method 1: Claude Code Configuration File + +Create or edit `~/.config/claude-code/mcp.json` (or the appropriate config location): + +```json +{ + "mcpServers": { + "gitea": { + "url": "http://10.43.241.50:3014", + "token": "your-mcp-token-here", + "description": "Gitea MCP server for repository management" + } + } +} +``` + +### Method 2: Environment Variables + +Set MCP server configuration via environment variables: + +```bash +export MCP_GITEA_URL="http://10.43.241.50:3014" +export MCP_GITEA_TOKEN="your-mcp-token-here" +``` + +### Method 3: Port Forward for Local Access + +If Claude Code runs locally (not in the cluster): + +```bash +# Forward the MCP server port to localhost +kubectl port-forward -n mcp svc/mcp-umbrella-gitea-mcp 3014:3014 + +# Then configure Claude Code to use localhost:3014 +``` + +## MCP Token Management + +### Where to Find MCP Tokens + +1. **Check Kubernetes Secrets:** + ```bash + kubectl get secrets -n mcp + kubectl get secret -n mcp -o yaml + ``` + +2. **Generate New Token:** + If your MCP server supports token generation, you can create new tokens via its API or management interface. + +### Token Security + +- MCP tokens are sensitive credentials +- Store them securely (use Kubernetes secrets, not in code) +- Rotate tokens periodically +- Use different tokens for different environments + +## Available MCP Tools + +Once connected, MCP tools will appear in Claude Code with the `mcp__` prefix, such as: + +- `mcp__gitea_create_repo` - Create a new repository +- `mcp__gitea_list_repos` - List repositories +- `mcp__gitea_push` - Push code to a repository +- `mcp__gitea_webhook` - Manage webhooks + +(Actual tool names depend on your MCP server implementation) + +## Using MCP in Future Deployments + +When you have MCP properly configured, Claude Code can automatically: + +1. **Create Gitea repositories** without manual API calls +2. **Push code** without entering credentials +3. **Trigger builds** by calling webhooks +4. **Monitor deployment** status +5. **Update configurations** in the cluster + +### Example Workflow with MCP + +```markdown +User: "Deploy my new app to Kubernetes" + +Claude will automatically: +1. Use mcp__gitea_create_repo to create the Git repository +2. Use mcp__gitea_push to push the code +3. Use mcp__kubectl_apply to create Kubernetes resources +4. Use mcp__flux_sync to trigger Flux reconciliation +5. Use mcp__kubectl_get to check deployment status +``` + +## Troubleshooting MCP Connection + +### Check if MCP is Connected + +In a Claude Code session, MCP tools should appear in the available functions list. They'll start with `mcp__`. + +### Connection Issues + +1. **MCP server not reachable:** + ```bash + curl http://10.43.241.50:3014/health + ``` + +2. **Token invalid:** + - Verify the token hasn't expired + - Check token permissions + - Generate a new token + +3. **Claude Code not detecting MCP:** + - Restart Claude Code + - Check configuration file syntax + - Verify MCP server is running + +### Testing MCP Access + +```bash +# Test MCP server is responding +curl -H "Authorization: Bearer YOUR_TOKEN" \ + http://10.43.241.50:3014/api/tools + +# Should return list of available MCP tools +``` + +## Setting Up MCP for Other Services + +The same pattern can be used for other services: + +### Harbor Registry MCP + +```json +{ + "mcpServers": { + "harbor": { + "url": "http://harbor-mcp-service:3015", + "token": "harbor-mcp-token", + "description": "Harbor registry management" + } + } +} +``` + +### Kubernetes MCP + +```json +{ + "mcpServers": { + "kubernetes": { + "url": "http://k8s-mcp-service:3016", + "token": "k8s-mcp-token", + "description": "Kubernetes cluster management" + } + } +} +``` + +## Benefits of MCP Integration + +1. **Automation** - No manual steps for common tasks +2. **Security** - Credentials managed centrally +3. **Efficiency** - Faster deployments +4. **Consistency** - Standardized workflows +5. **Error Reduction** - Less manual intervention + +## Future Enhancements + +Consider adding MCP servers for: + +- **ArgoCD** - GitOps deployments +- **Prometheus** - Metrics and monitoring +- **Vault** - Secrets management +- **Grafana** - Dashboard creation +- **AlertManager** - Alert configuration + +## Quick Reference + +### Current Setup (Without MCP) +```bash +# Manual steps required: +1. Create Gitea repo via web UI or API +2. Git push with credentials +3. kubectl apply manifests +4. Wait for Flux sync +``` + +### With MCP Connected +```bash +# Automated via Claude Code: +User: "Deploy this app" +# Claude handles everything automatically +``` + +## Resources + +- [MCP Specification](https://github.com/anthropics/anthropic-mcp) +- [Claude Code Documentation](https://docs.anthropic.com/claude/docs/claude-code) +- Your cluster's MCP server documentation + +--- + +**Note:** The specific MCP tools and configuration format may vary based on your MCP server implementation. Check your MCP server's documentation for exact details. diff --git a/setup-gitea.sh b/setup-gitea.sh new file mode 100755 index 0000000..b660864 --- /dev/null +++ b/setup-gitea.sh @@ -0,0 +1,90 @@ +#!/bin/bash +# Resume Site - Gitea Setup and Push Script + +set -e + +GITEA_URL="http://192.168.1.49:13001" +GITEA_USER="admin" +REPO_NAME="resume-site" + +echo "=== Resume Site - Gitea Setup ===" +echo "" +echo "This script will:" +echo "1. Create the Gitea repository (requires admin password)" +echo "2. Push the code to Gitea" +echo "3. Verify Flux is syncing" +echo "" + +# Prompt for password +read -sp "Enter Gitea admin password: " GITEA_PASSWORD +echo "" + +# Create repository via API +echo "Creating repository in Gitea..." +RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$GITEA_URL/api/v1/admin/users/$GITEA_USER/repos" \ + -u "$GITEA_USER:$GITEA_PASSWORD" \ + -H "Content-Type: application/json" \ + -d "{ + \"name\": \"$REPO_NAME\", + \"description\": \"Nicholas Haven Resume Site - Automated deployment via Flux CD\", + \"private\": false, + \"auto_init\": false + }") + +HTTP_CODE=$(echo "$RESPONSE" | tail -n1) +BODY=$(echo "$RESPONSE" | head -n-1) + +if [ "$HTTP_CODE" = "201" ]; then + echo "✓ Repository created successfully" +elif [ "$HTTP_CODE" = "409" ]; then + echo "✓ Repository already exists" +else + echo "⚠ API response: $HTTP_CODE" + echo "$BODY" +fi + +# Configure git remote +echo "" +echo "Configuring git remote..." +git remote remove origin 2>/dev/null || true +git remote add origin "http://$GITEA_USER:$GITEA_PASSWORD@192.168.1.49:13001/$GITEA_USER/$REPO_NAME.git" + +# Push code +echo "Pushing code to Gitea..." +git branch -M main +git push -u origin main + +echo "" +echo "✓ Code pushed successfully!" +echo "" + +# Clean up credentials from remote URL +git remote remove origin +git remote add origin "$GITEA_URL/$GITEA_USER/$REPO_NAME.git" + +echo "Waiting for Flux to sync..." +sleep 10 + +# Check Flux status +echo "" +echo "=== Flux Status ===" +kubectl get gitrepository -n flux-system resume-site +echo "" +kubectl get helmrelease -n default resume-site +echo "" + +# Check build trigger +echo "=== Build Trigger Status ===" +kubectl get cronjob -n resume-site resume-site-build-trigger +echo "" + +echo "=== Next Steps ===" +echo "" +echo "1. Monitor the build: kubectl get jobs -n flux-builds -l app=resume-site" +echo "2. Check build logs: kubectl logs -n flux-builds -l app=resume-site" +echo "3. Watch deployment: kubectl get pods -n default -l app.kubernetes.io/name=resume-site" +echo "4. Once deployed, visit: https://resume.caffeinetux.com" +echo "" +echo "The build trigger runs every 5 minutes and will automatically" +echo "build new images when you push commits to the main branch." +echo ""