bontaq · September 14, 2025 22:45
diff --git a/gistfile1.txt b/gistfile1.txt
 If you're like me you probably noticed Claude code not using Tidewave MCP enough.

 The process to create this was more or less:
 1. Tell Claude using Tidewave is extremely required
 2. Have it generate some docs on all the MCP functions
 3. Run through some tasks, each time asking Claude "could you have used Tidewave better?  update claude.md"

 After adding this you too should have claude do some self improvement, especially adding on to the 
 bottom "Real world power examples" and to adapt it to your project.  It's a beautiful, incredible thing 
 to see it working within the system instead of around the edges.

 Append this and have fun!:

 ## Tidewave MCP Tools - CRITICAL PRIORITY FOR ELIXIR DEVELOPMENT

 ### MANDATORY: Use Tidewave MCP Tools as Primary Interface

 When working with this Elixir/Phoenix codebase, **ALWAYS prioritize Tidewave MCP tools** over traditional file system operations. Tidewave provides deep integration with the Elixir runtime and superior code intelligence.

 ### Tool Usage Hierarchy

 #### 1. Code Evaluation - ALWAYS Use Tidewave
 **NEVER use Bash to run Elixir code!** Instead use `mcp__tidewave__project_eval`:
 - Test function behavior and debug issues
 - Explore modules and their functions
 - Access IEx helpers (e.g., `exports(Module)`, `h(Module.function)`)
 - Capture IO output
 - Pass arguments with the `arguments` parameter
 - Set custom timeout for long-running operations

 Example:
 - ❌ WRONG: `bash: mix run -e "IO.inspect(MyModule.function())"`
 - ✅ RIGHT: `mcp__tidewave__project_eval: code: "IO.inspect(MyModule.function())"`

 #### 2. Source Code Navigation - Tidewave First
 Before using Grep, Glob, or Read for Elixir code:

 **`mcp__tidewave__get_source_location`** - Find exact file locations instantly
 - Works with: `Module`, `Module.function`, `Module.function/arity`
 - Find dependencies: `"dep:package_name"`
 - FASTER than grep/glob for known modules

 **`mcp__tidewave__get_docs`** - Get documentation without reading files
 - Module docs: `"MyModule"`
 - Function docs: `"MyModule.function/2"`
 - Callback docs: `"c:GenServer.init/1"`

 Example:
 - ❌ WRONG: `grep: pattern: "defmodule Worker"`
 - ✅ RIGHT: `mcp__tidewave__get_source_location: reference: "Ezcrew.Staffing.Worker"`

 #### 3. Database Operations - Direct SQL Execution
 **`mcp__tidewave__execute_sql_query`** - Run SQL directly against Ecto repos
 - Inspect database schema
 - Query data (limited to 50 rows, use LIMIT/OFFSET for more)
 - Supports parameterized queries
 - Auto-detects available repositories
 - Returns native Elixir data structures

 **`mcp__tidewave__get_ecto_schemas`** - List all schemas and their locations
 - ALWAYS use this before searching for schema files
 - Returns module names with file paths

 Example:
 - ❌ WRONG: `bash: psql -c "SELECT * FROM users"`
 - ✅ RIGHT: `mcp__tidewave__execute_sql_query: query: "SELECT * FROM users LIMIT 10"`

 #### 4. Dependency Documentation
 **`mcp__tidewave__search_package_docs`** - Search Hex documentation
 - Searches project dependencies by default
 - Can target specific packages
 - Use BEFORE trying to read dependency source code

 #### 5. Error Diagnosis
 **`mcp__tidewave__get_logs`** - Get application logs
 - Filter with regex patterns
 - Tail recent entries
 - Essential for debugging runtime issues

 ### Workflow Patterns

 #### Understanding a Module
 1. FIRST: `mcp__tidewave__get_docs` - Get documentation
 2. THEN: `mcp__tidewave__get_source_location` - Find the file
 3. THEN: `mcp__tidewave__project_eval` with `exports(Module)` - List functions
 4. FINALLY: Read the file if needed for implementation details

 #### Testing Code Changes
 1. ALWAYS: Test with `mcp__tidewave__project_eval` before writing
 2. Example: `code: "MyModule.new_function(:test_input) |> IO.inspect()"`
 3. Verify behavior matches expectations
 4. Only then modify the actual file

 #### Database Work
 1. START: `mcp__tidewave__get_ecto_schemas` - Understand data models
 2. EXPLORE: `mcp__tidewave__execute_sql_query` - Inspect actual data
 3. TEST: `mcp__tidewave__project_eval` - Test Ecto queries
 4. IMPLEMENT: Make schema/migration changes

 #### Debugging Issues
 1. CHECK: `mcp__tidewave__get_logs` - Recent errors
 2. LOCATE: `mcp__tidewave__get_source_location` - Find problem code
 3. TEST: `mcp__tidewave__project_eval` - Reproduce issue
 4. FIX: Edit the file with the solution

 ### IEx Helpers Available in project_eval
 - `h(Module)` - Get help for a module
 - `exports(Module)` - List all exported functions
 - `i(value)` - Inspect data structure info
 - `t(Module)` - Show types defined in module
 - `b(Module)` - Show behaviours module implements
 - `arguments` - Access passed arguments array

 ### Database Query Gotchas
 When using `execute_sql_query`:
 - UUIDs return as 16-byte binaries - cast with `::text` (PostgreSQL)
 - Results limited to 50 rows - use LIMIT/OFFSET for pagination
 - Use parameterized queries: `query: "SELECT * FROM users WHERE id = $1", arguments: [123]`

 ### Common Mistakes to Avoid
 ❌ DON'T:
 - Use `bash` to run `mix` commands for code evaluation
 - Use `grep` to find module definitions when you know the module name
 - Read entire files to find function documentation
 - Run `iex` in bash instead of using `project_eval`
 - Search file system for Ecto schemas before using `get_ecto_schemas`

 ✅ DO:
 - Use `project_eval` for ALL Elixir code execution
 - Use `get_source_location` for known modules
 - Use `get_docs` for documentation
 - Use `get_ecto_schemas` first for schema discovery
 - Use Tidewave MCP tools as your primary interface

 ### Remember: Tidewave Is Your Superpower
 The Tidewave MCP server gives you:
 - Direct access to the running Elixir application
 - Instant code evaluation with full project context
 - Database introspection without external tools
 - Documentation at your fingertips
 - Source navigation faster than file search

 **Every time you reach for Bash, Grep, or Read for Elixir code, ask yourself: "Can Tidewave MCP do this better?" The answer is almost always YES.**

 ### Real-World Tidewave Power Examples
	If you're like me you probably noticed Claude code not using Tidewave MCP enough.

	The process to create this was more or less:
	1. Tell Claude using Tidewave is extremely required
	2. Have it generate some docs on all the MCP functions
	3. Run through some tasks, each time asking Claude "could you have used Tidewave better? update claude.md"

	After adding this you too should have claude do some self improvement, especially adding on to the
	bottom "Real world power examples" and to adapt it to your project. It's a beautiful, incredible thing
	to see it working within the system instead of around the edges.

	Append this and have fun!:

	## Tidewave MCP Tools - CRITICAL PRIORITY FOR ELIXIR DEVELOPMENT

	### MANDATORY: Use Tidewave MCP Tools as Primary Interface

	When working with this Elixir/Phoenix codebase, ALWAYS prioritize Tidewave MCP tools over traditional file system operations. Tidewave provides deep integration with the Elixir runtime and superior code intelligence.

	### Tool Usage Hierarchy

	#### 1. Code Evaluation - ALWAYS Use Tidewave
	NEVER use Bash to run Elixir code! Instead use `mcp__tidewave__project_eval`:
	- Test function behavior and debug issues
	- Explore modules and their functions
	- Access IEx helpers (e.g., `exports(Module)`, `h(Module.function)`)
	- Capture IO output
	- Pass arguments with the `arguments` parameter
	- Set custom timeout for long-running operations

	Example:
	- ❌ WRONG: `bash: mix run -e "IO.inspect(MyModule.function())"`
	- ✅ RIGHT: `mcp__tidewave__project_eval: code: "IO.inspect(MyModule.function())"`

	#### 2. Source Code Navigation - Tidewave First
	Before using Grep, Glob, or Read for Elixir code:

	`mcp__tidewave__get_source_location` - Find exact file locations instantly
	- Works with: `Module`, `Module.function`, `Module.function/arity`
	- Find dependencies: `"dep:package_name"`
	- FASTER than grep/glob for known modules

	`mcp__tidewave__get_docs` - Get documentation without reading files
	- Module docs: `"MyModule"`
	- Function docs: `"MyModule.function/2"`
	- Callback docs: `"c:GenServer.init/1"`

	Example:
	- ❌ WRONG: `grep: pattern: "defmodule Worker"`
	- ✅ RIGHT: `mcp__tidewave__get_source_location: reference: "Ezcrew.Staffing.Worker"`

	#### 3. Database Operations - Direct SQL Execution
	`mcp__tidewave__execute_sql_query` - Run SQL directly against Ecto repos
	- Inspect database schema
	- Query data (limited to 50 rows, use LIMIT/OFFSET for more)
	- Supports parameterized queries
	- Auto-detects available repositories
	- Returns native Elixir data structures

	`mcp__tidewave__get_ecto_schemas` - List all schemas and their locations
	- ALWAYS use this before searching for schema files
	- Returns module names with file paths

	Example:
	- ❌ WRONG: `bash: psql -c "SELECT * FROM users"`
	- ✅ RIGHT: `mcp__tidewave__execute_sql_query: query: "SELECT * FROM users LIMIT 10"`

	#### 4. Dependency Documentation
	`mcp__tidewave__search_package_docs` - Search Hex documentation
	- Searches project dependencies by default
	- Can target specific packages
	- Use BEFORE trying to read dependency source code

	#### 5. Error Diagnosis
	`mcp__tidewave__get_logs` - Get application logs
	- Filter with regex patterns
	- Tail recent entries
	- Essential for debugging runtime issues

	### Workflow Patterns

	#### Understanding a Module
	1. FIRST: `mcp__tidewave__get_docs` - Get documentation
	2. THEN: `mcp__tidewave__get_source_location` - Find the file
	3. THEN: `mcp__tidewave__project_eval` with `exports(Module)` - List functions
	4. FINALLY: Read the file if needed for implementation details

	#### Testing Code Changes
	1. ALWAYS: Test with `mcp__tidewave__project_eval` before writing
	2. Example: `code: "MyModule.new_function(:test_input) \|> IO.inspect()"`
	3. Verify behavior matches expectations
	4. Only then modify the actual file

	#### Database Work
	1. START: `mcp__tidewave__get_ecto_schemas` - Understand data models
	2. EXPLORE: `mcp__tidewave__execute_sql_query` - Inspect actual data
	3. TEST: `mcp__tidewave__project_eval` - Test Ecto queries
	4. IMPLEMENT: Make schema/migration changes

	#### Debugging Issues
	1. CHECK: `mcp__tidewave__get_logs` - Recent errors
	2. LOCATE: `mcp__tidewave__get_source_location` - Find problem code
	3. TEST: `mcp__tidewave__project_eval` - Reproduce issue
	4. FIX: Edit the file with the solution

	### IEx Helpers Available in project_eval
	- `h(Module)` - Get help for a module
	- `exports(Module)` - List all exported functions
	- `i(value)` - Inspect data structure info
	- `t(Module)` - Show types defined in module
	- `b(Module)` - Show behaviours module implements
	- `arguments` - Access passed arguments array

	### Database Query Gotchas
	When using `execute_sql_query`:
	- UUIDs return as 16-byte binaries - cast with `::text` (PostgreSQL)
	- Results limited to 50 rows - use LIMIT/OFFSET for pagination
	- Use parameterized queries: `query: "SELECT * FROM users WHERE id = $1", arguments: [123]`

	### Common Mistakes to Avoid
	❌ DON'T:
	- Use `bash` to run `mix` commands for code evaluation
	- Use `grep` to find module definitions when you know the module name
	- Read entire files to find function documentation
	- Run `iex` in bash instead of using `project_eval`
	- Search file system for Ecto schemas before using `get_ecto_schemas`

	✅ DO:
	- Use `project_eval` for ALL Elixir code execution
	- Use `get_source_location` for known modules
	- Use `get_docs` for documentation
	- Use `get_ecto_schemas` first for schema discovery
	- Use Tidewave MCP tools as your primary interface

	### Remember: Tidewave Is Your Superpower
	The Tidewave MCP server gives you:
	- Direct access to the running Elixir application
	- Instant code evaluation with full project context
	- Database introspection without external tools
	- Documentation at your fingertips
	- Source navigation faster than file search

	Every time you reach for Bash, Grep, or Read for Elixir code, ask yourself: "Can Tidewave MCP do this better?" The answer is almost always YES.

	### Real-World Tidewave Power Examples
No results found