claudetools/.claude/claude.md

ClaudeTools Project Context

Project Type: MSP Work Tracking System Status: Production-Ready Database: MariaDB 10.6.22 @ 172.16.3.30:3306 (RMM Server)

---

Quick Facts

• 95+ API Endpoints across 17 entities
• 38 Database Tables (fully migrated)
• JWT Authentication on all endpoints
• AES-256-GCM Encryption for credentials
• 3 MCP Servers configured (GitHub, Filesystem, Sequential Thinking)

---

Core Operating Principle: You Are a Coordinator

CRITICAL: Main Claude is a coordinator, not an executor. Your primary role is to delegate work to specialized agents and preserve your main context space.

Main Context Space is Sacred:

• Your context window is valuable and limited
• Delegate ALL significant operations to agents unless doing it yourself is significantly cheaper in tokens
• Agents have their own full context windows for specialized tasks
• Keep your context focused on coordination, decision-making, and user interaction

When to Delegate (via Task tool):

• Database operations (queries, inserts, updates) → Database Agent
• Code generation → Coding Agent
• Code review → Code Review Agent (MANDATORY for all code)
• Test execution → Testing Agent
• Git operations → Gitea Agent
• File exploration/search → Explore Agent
• Complex problem-solving → General-purpose agent with Sequential Thinking MCP

When to Do It Yourself:

• Simple user responses (conversational replies)
• Reading a single file to answer a question
• Basic file operations (1-2 files)
• Presenting agent results to user
• Making decisions about what to do next
• Creating task checklists

Example - Database Query (DELEGATE):

User: "How many projects are in the database?"

❌ WRONG: ssh guru@172.16.3.30 "mysql -u claudetools ... SELECT COUNT(*) ..."
✅ CORRECT: Launch Database Agent with task: "Count projects in database"

Example - Simple File Read (DO YOURSELF):

User: "What's in the README?"

✅ CORRECT: Use Read tool directly (cheap, preserves context)
❌ WRONG: Launch agent just to read one file (wasteful)

Rule of Thumb:

• If the operation will consume >500 tokens of your context → Delegate to agent
• If it's a simple read/search/response → Do it yourself
• If it's code generation or database work → ALWAYS delegate
• When in doubt → Delegate (agents are cheap, your context is precious)

See: .claude/AGENT_COORDINATION_RULES.md for complete delegation guidelines

---

Project Structure

D:\ClaudeTools/
├── api/                    # FastAPI application
│   ├── main.py            # API entry point
│   ├── models/            # SQLAlchemy models
│   ├── routers/           # API endpoints
│   ├── schemas/           # Pydantic schemas
│   ├── services/          # Business logic
│   ├── middleware/        # Auth & error handling
│   └── utils/             # Crypto utilities
├── migrations/            # Alembic database migrations
├── .claude/              # Claude Code hooks & config
│   ├── commands/         # Commands (create-spec, checkpoint)
│   ├── skills/           # Skills (frontend-design)
│   └── templates/        # Templates (app spec, prompts)
├── mcp-servers/          # MCP server implementations
│   └── feature-management/  # Feature tracking MCP server
├── scripts/              # Setup & test scripts
└── projects/             # Project workspaces

---

Database Connection

UPDATED 2026-01-17: Database is centralized on RMM server (172.16.3.30)

Connection String:

Host: 172.16.3.30:3306
Database: claudetools
User: claudetools
Password: CT_e8fcd5a3952030a79ed6debae6c954ed

Environment Variables:

DATABASE_URL=mysql+pymysql://claudetools:CT_e8fcd5a3952030a79ed6debae6c954ed@172.16.3.30:3306/claudetools?charset=utf8mb4

API Base URL: http://172.16.3.30:8001

See: .claude/agents/DATABASE_CONNECTION_INFO.md for complete details.

---

Starting the API

# Activate virtual environment
api\venv\Scripts\activate

# Start API server
python -m api.main
# OR
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

# Access documentation
http://localhost:8000/api/docs

---

Key API Endpoints

Core Entities (Phase 4)

• /api/machines - Machine inventory
• /api/clients - Client management
• /api/projects - Project tracking
• /api/sessions - Work sessions
• /api/tags - Tagging system

MSP Work Tracking (Phase 5)

• /api/work-items - Work item tracking
• /api/tasks - Task management
• /api/billable-time - Time & billing

Infrastructure (Phase 5)

• /api/sites - Physical locations
• /api/infrastructure - IT assets
• /api/services - Application services
• /api/networks - Network configs
• /api/firewall-rules - Firewall documentation
• /api/m365-tenants - M365 tenant management

Credentials (Phase 5)

• /api/credentials - Encrypted credential storage
• /api/credential-audit-logs - Audit trail (read-only)
• /api/security-incidents - Incident tracking

---

Common Workflows

1. Create New Project

# Create project
POST /api/projects
{
  "name": "New Website",
  "client_id": "client-uuid",
  "status": "planning"
}

2. Track Work Session

# Create session
POST /api/sessions
{
  "project_id": "project-uuid",
  "machine_id": "machine-uuid",
  "started_at": "2026-01-16T10:00:00Z"
}

# Log billable time
POST /api/billable-time
{
  "session_id": "session-uuid",
  "work_item_id": "work-item-uuid",
  "client_id": "client-uuid",
  "start_time": "2026-01-16T10:00:00Z",
  "end_time": "2026-01-16T12:00:00Z",
  "duration_hours": 2.0,
  "hourly_rate": 150.00,
  "total_amount": 300.00
}

3. Store Encrypted Credential

POST /api/credentials
{
  "credential_type": "api_key",
  "service_name": "OpenAI API",
  "username": "api_key",
  "password": "sk-1234567890",  # Auto-encrypted
  "client_id": "client-uuid",
  "notes": "Production API key"
}
# Password automatically encrypted with AES-256-GCM
# Audit log automatically created

---

Important Files

Session State: SESSION_STATE.md - Complete project history and status

Credentials: credentials.md - ALL infrastructure credentials and connection details (UNREDACTED for context recovery)

Session Logs: session-logs/YYYY-MM-DD-session.md - Comprehensive session documentation with credentials, decisions, and infrastructure changes

Documentation:

• AUTOCODER_INTEGRATION.md - AutoCoder resources guide
• TEST_PHASE5_RESULTS.md - Phase 5 test results

Configuration:

• .env - Environment variables (gitignored)
• .env.example - Template with placeholders

Tests:

• test_api_endpoints.py - Phase 4 tests
• test_phase5_api_endpoints.py - Phase 5 tests

AutoCoder Resources:

• .claude/commands/create-spec.md - Create app specification
• .claude/commands/checkpoint.md - Create development checkpoint
• .claude/skills/frontend-design/ - Frontend design skill
• .claude/templates/ - Prompt templates (4 templates)
• mcp-servers/feature-management/ - Feature tracking MCP server

---

Recent Work (from SESSION_STATE.md)

Last Session: 2026-01-18 Phases Completed: 0-5 (complete)

Phase 5 - Completed:

• MSP Work Tracking system
• Infrastructure management endpoints
• Encrypted credential storage
• Security incident tracking

Current State:

• 95+ endpoints operational
• All migrations applied (38 tables)
• Full test coverage

---

Security

Authentication: JWT tokens (Argon2 password hashing) Encryption: AES-256-GCM (Fernet) for credentials Audit Logging: All credential operations logged

Get JWT Token:

POST /api/auth/token
{
  "email": "user@example.com",
  "password": "your-password"
}

---

Troubleshooting

API won't start:

# Check if port 8000 is in use
netstat -ano | findstr :8000

# Check database connection
python test_db_connection.py

Database migration issues:

# Check current revision
alembic current

# Show migration history
alembic history

# Upgrade to latest
alembic upgrade head

---

MCP Servers

Model Context Protocol servers extend Claude Code's capabilities.

Configured Servers:

• GitHub MCP - Repository and PR management (requires token)
• Filesystem MCP - Enhanced file operations (D:\ClaudeTools access)
• Sequential Thinking MCP - Structured problem-solving

Configuration: .mcp.json (project-scoped) Documentation: MCP_SERVERS.md - Complete setup and usage guide Setup Script: bash scripts/setup-mcp-servers.sh

Quick Start:

1. Add GitHub token to .mcp.json (optional)
2. Restart Claude Code completely
3. Test: "Use sequential thinking to analyze X"
4. Test: "List Python files in the api directory"

Note: GitHub MCP is for GitHub.com - Gitea integration requires custom solution (see MCP_SERVERS.md)

---

Next Steps (Optional Phase 7)

Remaining entities (from original spec):

• File Changes API - Track file modifications
• Command Runs API - Command execution history
• Problem Solutions API - Knowledge base
• Failure Patterns API - Error pattern recognition
• Environmental Insights API - Contextual learning

These are optional - the system is fully functional without them.

---

Coding Guidelines

IMPORTANT: Follow coding standards in .claude/CODING_GUIDELINES.md

Key Rules:

• NO EMOJIS - EVER (causes encoding/parsing issues)
• Use ASCII text markers: [OK], [ERROR], [WARNING], [SUCCESS]
• Follow PEP 8 for Python, PSScriptAnalyzer for PowerShell
• No hardcoded credentials
• All endpoints must have docstrings

---

Context Recovery & Session Logs

CRITICAL: Use /context command when user references previous work

Session Logs (session-logs/)

• Format: session-logs/YYYY-MM-DD-session.md
• Content: ALL credentials, infrastructure details, decisions, commands, config changes
• Purpose: Full context recovery when conversation is summarized or new session starts
• Usage: /save command creates/appends to today's session log

Credentials File (credentials.md)

• Content: ALL infrastructure credentials (UNREDACTED)
• Sections:
  • Infrastructure - SSH Access (GuruRMM, Jupiter, AD2, D2TESTNAS)
  • Services - Web Applications (Gitea, ClaudeTools API)
  • Projects - ClaudeTools (Database, API auth, encryption keys)
  • Projects - Dataforth DOS (Update workflow, key files, folder structure)
• Purpose: Centralized credentials for immediate context recovery
• Usage: /context searches this file for server access details

Context Recovery Workflow

When user references previous work:

1. Use /context command - Searches session logs and credentials.md
2. Never ask user for information already in logs/credentials
3. Apply found information - Connect to servers, continue work
4. Report findings - Summarize relevant credentials and previous work

Example Usage

User: "Connect to the Dataforth NAS"
Assistant: Uses /context to find D2TESTNAS credentials (192.168.0.9, admin, Paper123!@#-nas)
Assistant: Connects using found credentials without asking user

---

Quick Reference

Start API: uvicorn api.main:app --reload API Docs: http://localhost:8000/api/docs (local) or http://172.16.3.30:8001/api/docs (RMM) Setup MCP Servers: bash scripts/setup-mcp-servers.sh Database: 172.16.3.30:3306/claudetools (RMM Server) Virtual Env: api\venv\Scripts\activate Coding Guidelines: .claude/CODING_GUIDELINES.md MCP Documentation: MCP_SERVERS.md AutoCoder Integration: AUTOCODER_INTEGRATION.md

Available Commands:

• /create-spec - Create app specification
• /checkpoint - Create development checkpoint
• /save - Save comprehensive session log (credentials, infrastructure, decisions)
• /context - Search session logs and credentials.md for previous work
• /sync - Sync ClaudeTools configuration from Gitea repository

Available Skills:

• /frontend-design - Modern frontend design patterns

---

Last Updated: 2026-01-19 (Integrated C: drive behavioral rules, added context recovery system) Project Progress: Phase 5 Complete