Klomgor · pull · Jul 2, 2025 · Jul 2, 2025 · Jul 2, 2025 · Jul 2, 2025
diff --git a/.mcp.json b/.mcp.json
@@ -0,0 +1,36 @@
+{
+	"mcpServers": {
+		"go-language-server": {
+			"type": "stdio",
+			"command": "go",
+			"args": [
+				"run",
+				"github.com/isaacphi/mcp-language-server@latest",
+				"-workspace",
+				"./",
+				"-lsp",
+				"go",
+				"--",
+				"run",
+				"golang.org/x/tools/gopls@latest"
+			],
+			"env": {}
+		},
+		"typescript-language-server": {
+			"type": "stdio",
+			"command": "go",
+			"args": [
+				"run",
+				"github.com/isaacphi/mcp-language-server@latest",
+				"-workspace",
+				"./site/",
+				"-lsp",
+				"pnpx",
+				"--",
+				"typescript-language-server",
+				"--stdio"
+			],
+			"env": {}
+		}
+	}
+}
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -89,6 +89,10 @@ Read [cursor rules](.cursorrules).
    - Format: `{number}_{description}.{up|down}.sql`
    - Number must be unique and sequential
    - Always include both up and down migrations
+   - **Use helper scripts**:
+     - `./coderd/database/migrations/create_migration.sh "migration name"` - Creates new migration files
+     - `./coderd/database/migrations/fix_migration_numbers.sh` - Renumbers migrations to avoid conflicts
+     - `./coderd/database/migrations/create_fixture.sh "fixture name"` - Creates test fixtures for migrations
 
 2. **Update database queries**:
    - MUST DO! Any changes to database - adding queries, modifying queries should be done in the `coderd/database/queries/*.sql` files
@@ -125,6 +129,29 @@ Read [cursor rules](.cursorrules).
 4. Run `make gen` again
 5. Run `make lint` to catch any remaining issues
 
+### In-Memory Database Testing
+
+When adding new database fields:
+
+- **CRITICAL**: Update `coderd/database/dbmem/dbmem.go` in-memory implementations
+- The `Insert*` functions must include ALL new fields, not just basic ones
+- Common issue: Tests pass with real database but fail with in-memory database due to missing field mappings
+- Always verify in-memory database functions match the real database schema after migrations
+
+Example pattern:
+
+```go
+// In dbmem.go - ensure ALL fields are included
+code := database.OAuth2ProviderAppCode{
+    ID:                  arg.ID,
+    CreatedAt:           arg.CreatedAt,
+    // ... existing fields ...
+    ResourceUri:         arg.ResourceUri,         // New field
+    CodeChallenge:       arg.CodeChallenge,       // New field
+    CodeChallengeMethod: arg.CodeChallengeMethod, // New field
+}
+```
+
 ## Architecture
 
 ### Core Components
@@ -209,6 +236,12 @@ When working on OAuth2 provider features:
    - Avoid dependency on referer headers for security decisions
    - Support proper state parameter validation
 
+6. **RFC 8707 Resource Indicators**:
+   - Store resource parameters in database for server-side validation (opaque tokens)
+   - Validate resource consistency between authorization and token requests
+   - Support audience validation in refresh token flows
+   - Resource parameter is optional but must be consistent when provided
+
 ### OAuth2 Error Handling Pattern
 
 ```go
@@ -237,6 +270,114 @@ if errors.Is(err, errInvalidPKCE) {
 - Test both positive and negative cases
 - Use `testutil.WaitLong` for timeouts in tests
 
+## Code Navigation and Investigation
+
+### Using Go LSP Tools (STRONGLY RECOMMENDED)
+
+**IMPORTANT**: Always use Go LSP tools for code navigation and understanding. These tools provide accurate, real-time analysis of the codebase and should be your first choice for code investigation.
+
+When working with the Coder codebase, leverage Go Language Server Protocol tools for efficient code navigation:
+
+1. **Find function definitions** (USE THIS FREQUENTLY):
+
+   ```none
+   mcp__go-language-server__definition symbolName
+   ```
+
+   - Example: `mcp__go-language-server__definition getOAuth2ProviderAppAuthorize`
+   - Example: `mcp__go-language-server__definition ExtractAPIKeyMW`
+   - Quickly jump to function implementations across packages
+   - **Use this when**: You see a function call and want to understand its implementation
+   - **Tip**: Include package prefix if symbol is ambiguous (e.g., `httpmw.ExtractAPIKeyMW`)
+
+2. **Find symbol references** (ESSENTIAL FOR UNDERSTANDING IMPACT):
+
+   ```none
+   mcp__go-language-server__references symbolName
+   ```
+
+   - Example: `mcp__go-language-server__references APITokenFromRequest`
+   - Locate all usages of functions, types, or variables
+   - Understand code dependencies and call patterns
+   - **Use this when**: Making changes to understand what code might be affected
+   - **Critical for**: Refactoring, deprecating functions, or understanding data flow
+
+3. **Get symbol information** (HELPFUL FOR TYPE INFO):
+
+   ```none
+   mcp__go-language-server__hover filePath line column
+   ```
+
+   - Example: `mcp__go-language-server__hover /Users/thomask33/Projects/coder/coderd/httpmw/apikey.go 560 25`
+   - Get type information and documentation at specific positions
+   - **Use this when**: You need to understand the type of a variable or return value
+
+4. **Edit files using LSP** (WHEN MAKING TARGETED CHANGES):
+
+   ```none
+   mcp__go-language-server__edit_file filePath edits
+   ```
+
+   - Make precise edits using line numbers
+   - **Use this when**: You need to make small, targeted changes to specific lines
+
+5. **Get diagnostics** (ALWAYS CHECK AFTER CHANGES):
+
+   ```none
+   mcp__go-language-server__diagnostics filePath
+   ```
+
+   - Check for compilation errors, unused imports, etc.
+   - **Use this when**: After making changes to ensure code is still valid
+
+### LSP Tool Usage Priority
+
+**ALWAYS USE THESE TOOLS FIRST**:
+
+- **Use LSP `definition`** instead of manual searching for function implementations
+- **Use LSP `references`** instead of grep when looking for function/type usage
+- **Use LSP `hover`** to understand types and signatures
+- **Use LSP `diagnostics`** after making changes to check fo
F5B6
r errors
+
+**When to use other tools**:
+
+- **Use Grep for**: Text-based searches, finding patterns across files, searching comments
+- **Use Bash for**: Running tests, git commands, build operations
+- **Use Read tool for**: Reading configuration files, documentation, non-Go files
+
+### Investigation Strategy (LSP-First Approach)
+
+1. **Start with route registration** in `coderd/coderd.go` to understand API endpoints
+2. **Use LSP `definition` lookup** to trace from route handlers to actual implementations
+3. **Use LSP `references`** to understand how functions are called throughout the codebase
+4. **Follow the middleware chain** using LSP tools to understand request processing flow
+5. **Check test files** for expected behavior and error patterns
+6. **Use LSP `diagnostics`** to ensure your changes don't break compilation
+
+### Common LSP Workflows
+
+**Understanding a new feature**:
+
+1. Use `grep` to find the main entry point (e.g., route registration)
+2. Use LSP `definition` to jump to handler implementation
+3. Use LSP `references` to see how the handler is used
+4. Use LSP `definition` on each function call within the handler
+
+**Making changes to existing code**:
+
+1. Use LSP `references` to understand the impact of your changes
+2. Use LSP `definition` to understand the current implementation
+3. Make your changes using `Edit` or LSP `edit_file`
+4. Use LSP `diagnostics` to verify your changes compile correctly
+5. Run tests to ensure functionality still works
+
+**Debugging issues**:
+
+1. Use LSP `definition` to find the problematic function
+2. Use LSP `references` to trace how the function is called
+3. Use LSP `hover` to understand parameter types and return values
+4. Use `Read` to examine the full context around the issue
+
 ## Testing Scripts
 
 ### OAuth2 Test Scripts
@@ -265,3 +406,6 @@ Always run the full test suite after OAuth2 changes:
 4. **Missing newlines** - Ensure files end with newline character
 5. **Tests passing locally but failing in CI** - Check if `dbmem` implementation needs updating
 6. **OAuth2 endpoints returning wrong error format** - Ensure OAuth2 endpoints return RFC 6749 compliant errors
+7. **OAuth2 tests failing but scripts working** - Check in-memory database implementations in `dbmem.go`
+8. **Resource indicator validation failing** - Ensure database stores and retrieves resource parameters correctly
+9. **PKCE tests failing** - Verify both authorization code storage and token exchange handle PKCE fields
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go