chihlasm/resolutionflow
1
0
Fork 0
Code Issues 23 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Update CLAUDE-SETUP.md with postgres MCP and current project state

Browse Source 
- Added PostgreSQL MCP server documentation
- Updated project context with accurate tech stack
- Documented complete backend implementation
- Added development workflow and file structure
- Noted Fetch MCP unavailability with alternatives
This commit is contained in:
Michael Chihlas
2026-01-27 18:54:04 -05:00
parent 6a0f9cfc4a
commit bf383c975b
1 changed files with 276 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

296
CLAUDE-SETUP.md
View File

@@ -15,6 +15,7 @@ This document catalogs all tools, plugins, and MCP servers available to Claude C
### File Operations
#### Read
- **Purpose**: Read file contents from the filesystem
- **Capabilities**:
- Reads up to 2000 lines by default
@@ -24,6 +25,7 @@ This document catalogs all tools, plugins, and MCP servers available to Claude C
- **When to use**: Always read files before editing them; use for examining code, configs, or documentation
#### Edit
- **Purpose**: Perform exact string replacements in files
- **Capabilities**:
- Replaces `old_string` with `new_string`
@@ -33,12 +35,14 @@ This document catalogs all tools, plugins, and MCP servers available to Claude C
- **Requirements**: Must read file first before editing
#### Write
- **Purpose**: Create new files or overwrite existing ones
- **Capabilities**: Writes complete file content
- **When to use**: Only for creating genuinely new files; avoid for existing files (use Edit instead)
- **Requirements**: Must read file first if it exists
#### NotebookEdit
- **Purpose**: Edit Jupyter notebook (.ipynb) cells
- **Capabilities**:
- Replace, insert, or delete cells
@@ -48,6 +52,7 @@ This document catalogs all tools, plugins, and MCP servers available to Claude C
### Search & Discovery
#### Glob
- **Purpose**: Fast file pattern matching
- **Capabilities**:
- Supports glob patterns like `**/*.js`, `src/**/*.ts`
@@ -56,6 +61,7 @@ This document catalogs all tools, plugins, and MCP servers available to Claude C
- **Example**: `**/*.py` to find all Python files
#### Grep
- **Purpose**: Powerful content search (built on ripgrep)
- **Capabilities**:
- Full regex support
@@ -69,6 +75,7 @@ This document catalogs all tools, plugins, and MCP servers available to Claude C
### Execution & System
#### Bash
- **Purpose**: Execute bash commands
- **Capabilities**:
- Git operations
@@ -84,16 +91,19 @@ This document catalogs all tools, plugins, and MCP servers available to Claude C
- Never skip git hooks unless explicitly requested
#### TaskOutput
- **Purpose**: Retrieve output from running/completed background tasks
- **When to use**: Check status of background shells or agents
#### TaskStop
- **Purpose**: Stop running background tasks
- **When to use**: Terminate long-running processes
### Planning & Task Management
#### TodoWrite
- **Purpose**: Create and manage structured task lists
- **Capabilities**:
- Track tasks with states: pending, in_progress, completed
@@ -106,6 +116,7 @@ This document catalogs all tools, plugins, and MCP servers available to Claude C
- **Best practice**: Mark todos completed immediately after finishing; maintain exactly ONE in_progress task at a time
#### EnterPlanMode / ExitPlanMode
- **Purpose**: Enter planning mode for implementation design
- **When to use**:
- New feature implementation
@@ -116,6 +127,7 @@ This document catalogs all tools, plugins, and MCP servers available to Claude C
- **When NOT to use**: Simple one-line fixes, trivial tasks, pure research
#### AskUserQuestion
- **Purpose**: Ask user questions during execution
- **Capabilities**:
- Multiple choice questions (2-4 options)
@@ -126,6 +138,7 @@ This document catalogs all tools, plugins, and MCP servers available to Claude C
### Web & Information
#### WebFetch
- **Purpose**: Fetch and analyze web content
- **Capabilities**:
- Converts HTML to markdown
@@ -135,6 +148,7 @@ This document catalogs all tools, plugins, and MCP servers available to Claude C
- **Note**: For GitHub URLs, prefer `gh` CLI via Bash
#### WebSearch
- **Purpose**: Search the web for current information
- **Capabilities**:
- Access to up-to-date information beyond knowledge cutoff
@@ -143,6 +157,7 @@ This document catalogs all tools, plugins, and MCP servers available to Claude C
- **When to use**: Current events, recent documentation, external references
#### ToolSearch
- **Purpose**: Load deferred MCP tools before use
- **Capabilities**:
- Keyword search mode (e.g., "slack", "notebook")
@@ -158,16 +173,19 @@ This document catalogs all tools, plugins, and MCP servers available to Claude C
The Task tool launches specialized agents for complex work. Each agent type has specific capabilities:
### Bash Agent
- **Specialty**: Command execution
- **Tools**: Bash only
- **When to use**: Git operations, complex command sequences
### general-purpose Agent
- **Specialty**: Complex research and multi-step tasks
- **Tools**: All tools
- **When to use**: Complex questions, keyword searches requiring multiple attempts
### Explore Agent
- **Specialty**: Fast codebase exploration
- **Tools**: Read-only tools (Glob, Grep, Read, etc.)
- **Thoroughness levels**: quick, medium, very thorough
@@ -178,11 +196,13 @@ The Task tool launches specialized agents for complex work. Each agent type has
- **Critical**: Use this instead of manual Glob/Grep for exploratory searches
### Plan Agent
- **Specialty**: Implementation planning and architecture design
- **Tools**: Read-only tools
- **When to use**: Design implementation strategy, identify critical files, consider architectural trade-offs
### feature-dev Agents
- **code-architect**: Design feature architectures
- **code-explorer**: Analyze existing features and patterns
- **code-reviewer**: Review code for bugs and quality issues
@@ -194,15 +214,18 @@ The Task tool launches specialized agents for complex work. Each agent type has
Skills are invoked when users reference slash commands (e.g., `/commit`).
### feature-dev:feature-dev
- **Purpose**: Guided feature development with architecture focus
- **When to use**: Building new features from scratch
### frontend-design:frontend-design
- **Purpose**: Create production-grade frontend interfaces
- **When to use**: Building web components, pages, or applications
- **Goal**: Avoid generic AI aesthetics; create polished, distinctive designs
### Figma Integration Skills
- **figma:code-connect-components**: Map Figma designs to code components
- **figma:create-design-system-rules**: Generate custom design system rules
- **figma:implement-design**: Translate Figma designs to production code
@@ -215,9 +238,11 @@ Skills are invoked when users reference slash commands (e.g., `/commit`).
These tools must be loaded via ToolSearch before use.
### GitHub MCP Server
**Prefix**: `mcp__github__*`
**Available Operations**:
- **Repository**: create, fork, search repositories
- **Files**: get contents, create/update files, push files
- **Branches**: create, list commits
@@ -228,9 +253,11 @@ These tools must be loaded via ToolSearch before use.
**When to use**: GitHub operations beyond what `gh` CLI provides
### Filesystem MCP Server
**Prefix**: `mcp__filesystem__*`
**Available Operations**:
- **Read**: read_file, read_text_file, read_media_file, read_multiple_files
- **Write**: write_file, edit_file
- **Directory**: create, list, tree, list_with_sizes
@@ -240,9 +267,11 @@ These tools must be loaded via ToolSearch before use.
**When to use**: Complex filesystem operations; prefer built-in Read/Write/Edit for simple operations
### MS365 MCP Server
**Prefix**: `mcp__ms365__*`
**Available Operations**:
- **Authentication**: login, logout, verify, list/select/remove accounts
- **Teams**: chat operations, channel messages, team management
- **OneDrive**: file operations, Excel operations (worksheets, charts, ranges)
@@ -254,45 +283,265 @@ These tools must be loaded via ToolSearch before use.
**When to use**: Integration with Microsoft 365 services
### PostgreSQL MCP Server
**Prefix**: `mcp__postgres__*`
**Connection Details**:
- **Connection String**: `postgresql://postgres:postgres@localhost:5432/apoklisis`
- **Container Name**: `apoklisis_postgres`
- **Database Version**: PostgreSQL 16 Alpine
- **Docker Requirement**: Docker Desktop must be running
**Available Operations**:
- **Query**: Execute SQL queries directly
- **Schema Inspection**: View tables, columns, indexes, constraints
- **JSONB Analysis**: Inspect tree_structure and session path data
- **Migration Verification**: Confirm Alembic migrations applied correctly
- **Data Debugging**: Check auth tokens, user roles, tree categories
- **Performance**: Analyze query plans, check indexes
**When to use**:
- Debugging database issues
- Inspecting JSONB tree structures in `trees` table
- Verifying user authentication data
- Checking session path tracking
- Validating migration results
- Analyzing full-text search indexes
- Direct SQL queries for complex operations
**Common Use Cases**:
```sql
-- View all trees with their categories
SELECT id, name, category, version, is_deleted FROM trees;
-- Inspect JSONB tree structure
SELECT id, name, tree_structure FROM trees WHERE id = '<uuid>';
-- Check user authentication
SELECT id, email, role, team_id, is_active FROM users;
-- View active sessions
SELECT s.id, u.email, t.name, s.current_node_id, s.status
FROM sessions s
JOIN users u ON s.user_id = u.id
JOIN trees t ON s.tree_id = t.id;
```
### Fetch MCP Server
**Status**: ❌ Failed to install
**Alternative**: Use Bash tool with `curl` or PowerShell's `Invoke-RestMethod` for API testing
**Example - Testing FastAPI endpoints**:
```bash
# PowerShell example
$response = Invoke-RestMethod -Uri "http://localhost:8000/api/v1/trees" -Method GET -Headers @{"Authorization"="Bearer <token>"}
# Curl example (if available)
curl -X GET "http://localhost:8000/api/v1/trees" -H "Authorization: Bearer <token>"
```
**When to use Bash for API testing**:
- Testing authentication flow (register, login, refresh)
- Verifying endpoint responses
- Testing file uploads for attachments
- Validating export formats (md/txt/html)
- Checking error handling
---
## Project-Specific Context: Apoklisis
### Environment
- **Repository**: Git repository on main branch
- **Platform**: Windows (win32)
- **IDE**: VSCode with native Claude Code extension
- **Recent Activity**:
- Backend fixes: passlib/bcrypt integration (pinned bcrypt to 4.1.2)
- DateTime timezone issue fixes
- Clean working tree (as of last snapshot)
### Project Overview
**Apoklisis** is a troubleshooting decision tree web application designed for MSP (Managed Service Provider) engineers. The application allows engineers to create, manage, and navigate through decision trees for common IT support scenarios, improving troubleshooting consistency and efficiency.
### Technology Stack
**Backend (Complete)**:
- **Framework**: FastAPI (Python)
- **Database**: PostgreSQL 16 Alpine
- **ORM**: SQLAlchemy 2.0 (async)
- **Authentication**: JWT tokens (15-min access, 7-day refresh)
- **Password Hashing**: bcrypt (via passlib, pinned to 4.1.2 for compatibility)
- **API Endpoints**: 18 RESTful endpoints
- **Containerization**: Docker (apoklisis_postgres container)
- **Migrations**: Alembic
**Frontend (Not Started)**:
- **Framework**: React (planned)
- **Styling**: Tailwind CSS (planned)
- **Status**: Awaiting development
**Infrastructure**:
- **Development**: Local Docker PostgreSQL
- **Deployment Target**: Render (dev) / Railway Pro (production)
### Database Schema
**5 Core Tables**:
1. **users**: User accounts with roles (admin, engineer, viewer), team associations
2. **teams**: Team groupings for multi-tenant support
3. **trees**: Decision trees with JSONB `tree_structure` field, versioning, categories
4. **sessions**: Troubleshooting sessions with path tracking (JSONB)
5. **attachments**: File attachments linked to sessions
**Key Features**:
- UUID primary keys via PostgreSQL `gen_random_uuid()`
- JSONB for flexible tree structures and session paths
- Full-text search using PostgreSQL `to_tsvector`
- Soft deletes for trees (`is_deleted` flag)
- Timezone-aware timestamps
### Current Development Phase
**Phase 1a: Backend API** - ✅ **COMPLETE**
- All 18 API endpoints implemented
- Database schema finalized
- Authentication system working
- Password hashing fixed (bcrypt compatibility)
- Database naming standardized
**Phase 1b: Pre-built Trees** - 🔄 **Next Up**
- Create seed data script
- Implement 5 example troubleshooting trees from `TS-EXAMPLES.md`
**Phase 2: React Frontend** - ⏳ **Planned**
- Tree navigation interface
- Session management UI
- Admin panel for tree CRUD operations
### Backend File Structure
```
backend/
├── alembic/ # Database migrations
│ ├── versions/
│ │ └── 001_initial_schema.py
│ └── env.py
├── app/
│ ├── api/
│ │ ├── endpoints/
│ │ │ ├── auth.py # /api/v1/auth/* (register, login, refresh)
│ │ │ ├── trees.py # /api/v1/trees/* (CRUD, search)
│ │ │ └── sessions.py # /api/v1/sessions/* (tracking, export)
│ │ ├── deps.py # Auth dependencies (JWT validation)
│ │ └── router.py # Main API router
│ ├── core/
│ │ ├── config.py # Pydantic settings
│ │ ├── database.py # Async SQLAlchemy setup
│ │ └── security.py # JWT + bcrypt utilities
│ ├── models/ # SQLAlchemy models
│ │ ├── user.py
│ │ ├── team.py
│ │ ├── tree.py
│ │ ├── session.py
│ │ └── attachment.py
│ ├── schemas/ # Pydantic schemas
│ │ ├── user.py
│ │ ├── token.py
│ │ ├── tree.py
│ │ └── session.py
│ └── main.py # FastAPI app entry point
├── docker-compose.yml # PostgreSQL container definition
├── requirements.txt
├── .env.example
└── README.md
```
### Development Workflow
**Starting the Backend**:
```bash
# 1. Start PostgreSQL container
cd backend
docker-compose up -d
# 2. Activate Python virtual environment
venv\Scripts\activate # Windows
# source venv/bin/activate # Linux/Mac
# 3. Run migrations (if not already applied)
alembic upgrade head
# 4. Start FastAPI development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
# 5. Access API documentation
# http://localhost:8000/api/docs
```
**Database Connection**:
- **Host**: localhost:5432
- **Database**: apoklisis
- **User**: postgres
- **Password**: postgres
- **Container**: apoklisis_postgres
### Recent Work & Git History
**Recent Commits**:
### Recent Commits
```
a3efe68 Committing before moving to local disk
a6fc86c Pin bcrypt version to 4.1.2 for passlib compatibility
fa632da Fix backend: add passlib/bcrypt, fix datetime timezone issues
```
### Technology Stack (Inferred)
- **Backend**: Python (passlib, bcrypt for authentication)
- **Key Considerations**:
- Password hashing with passlib
- Timezone handling for datetime operations
- Dependency version compatibility (bcrypt pinned)
**Key Issues Resolved**:
- Bcrypt version pinned to 4.1.2 for passlib compatibility
- DateTime timezone handling corrected (timezone-aware timestamps)
- Database naming standardized across all tables
**Current Repository State**:
- Branch: main
- Working tree: Modified files (PROGRESS.md, CLAUDE-SETUP.md)
- Backend: Fully operational, untested in production
- Frontend: Not started
### File Reference Format
When referencing code in VSCode, use markdown links:
- Files: `[filename.ts](src/filename.ts)`
- Specific lines: `[filename.ts:42](src/filename.ts#L42)`
- Line ranges: `[filename.ts:42-51](src/filename.ts#L42-L51)`
- Folders: `[src/utils/](src/utils/)`
- Files: `[filename.py](backend/app/api/endpoints/auth.py)`
- Specific lines: `[auth.py:42](backend/app/api/endpoints/auth.py#L42)`
- Line ranges: `[auth.py:42-51](backend/app/api/endpoints/auth.py#L42-L51)`
- Folders: `[backend/app/api/](backend/app/api/)`
### Important Reference Files
- **[PROGRESS.md](PROGRESS.md)**: Development progress tracker
- **[02-TECHNICAL-ARCHITECTURE.md](02-TECHNICAL-ARCHITECTURE.md)**: Complete technical specification
- **[05-QUESTIONS-AND-ACTION-ITEMS.md](05-QUESTIONS-AND-ACTION-ITEMS.md)**: Design decisions log
- **[TS-EXAMPLES.md](TS-EXAMPLES.md)**: 5 example troubleshooting trees for Phase 1b
- **[backend/README.md](backend/README.md)**: Backend setup instructions
---
## Development Guidelines
### General Workflow
1. **Read First**: Always read files before editing
2. **Plan Complex Tasks**: Use TodoWrite for multi-step work
3. **Use Specialized Tools**: Prefer dedicated tools over bash commands for file operations
@@ -300,6 +549,7 @@ When referencing code in VSCode, use markdown links:
5. **Parallel Execution**: Make independent tool calls in parallel when possible
### Code Modification Principles
- **Avoid Over-Engineering**: Only make requested changes
- **No Premature Abstraction**: Don't create utilities for one-time operations
- **Security First**: Watch for command injection, XSS, SQL injection, OWASP Top 10
@@ -307,6 +557,7 @@ When referencing code in VSCode, use markdown links:
- **No Unnecessary Additions**: Don't add error handling for impossible scenarios
### Git Best Practices
- **Never** update git config
- **Never** run destructive commands (push --force, reset --hard) without explicit request
- **Never** skip hooks (--no-verify, --no-gpg-sign)
@@ -316,10 +567,12 @@ When referencing code in VSCode, use markdown links:
- **Include** co-author tag: `Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>`
### Pull Request Workflow
1. Run `git status`, `git diff`, check branch state
2. Analyze ALL commits from branch divergence (not just latest)
3. Keep PR title under 70 characters
4. Use HEREDOC for PR body with format:
```
## Summary
<1-3 bullet points>
@@ -331,6 +584,7 @@ When referencing code in VSCode, use markdown links:
```
### Communication Style
- **Concise**: Short, focused responses for CLI display
- **No Emojis**: Unless explicitly requested
- **No Time Estimates**: Never predict how long tasks will take
@@ -338,9 +592,10 @@ When referencing code in VSCode, use markdown links:
- **Direct**: Use markdown formatting, output text directly (not via echo/bash)
### When to Ask for Help
- **User Questions**: Use AskUserQuestion for clarifications
- **Planning**: Use EnterPlanMode for complex implementation decisions
- **Feedback**: Direct users to https://github.com/anthropics/claude-code/issues
- **Feedback**: Direct users to <https://github.com/anthropics/claude-code/issues>
---
@@ -395,6 +650,7 @@ Need to ask user a question?
## Security Policy
**Defensive Security Only**
- Assist with security analysis, detection rules, vulnerability explanations
- Create defensive tools and security documentation
- **Refuse**: Code for malicious use, credential harvesting, bulk SSH key/cookie/wallet crawling