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)

---

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

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

---

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

Available Skills:

• /frontend-design - Modern frontend design patterns

---

Last Updated: 2026-01-18 (Context system removed) Project Progress: Phase 5 Complete