aj/RoslynBridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update agent guide and SKILL docs; standardize Web API port 5001

Browse Source 
- Update .claude SKILL to use port 5001 in all examples
- Add repo-root SKILL.md consolidated API guide
- Expand AGENTS.md with rb.ps1 usage and policies
This commit is contained in:
AJ Isaacs
2025-10-28 18:18:45 -04:00
parent daa60c53dd
commit 86500af544
3 changed files with 346 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
.claude/skills/roslyn-bridge/SKILL.md
View File

@@ -11,14 +11,14 @@ Use this guide when accessing the Roslyn Bridge for C# code analysis.
``` ```
┌─────────────┐ REST API ┌────────────────────┐ HTTP ┌─────────────────────┐ ┌─────────────┐ REST API ┌────────────────────┐ HTTP ┌─────────────────────┐
│ Claude │ ◄─────────────────► │ Web API (:5000) │ ◄────────────► │ VS Plugin (:59123) │ │ Claude │ ◄─────────────────► │ Web API (:5001) │ ◄────────────► │ VS Plugin (:59123) │
│ AI │ │ Middleware │ │ Roslyn Bridge │ │ AI │ │ Middleware │ │ Roslyn Bridge │
└─────────────┘ └────────────────────┘ └─────────────────────┘ └─────────────┘ └────────────────────┘ └─────────────────────┘
``` ```
## Recommended: Web API (Port 5000) ## Recommended: Web API (Port 5001)
**Base URL**: `http://localhost:5000` **Base URL**: `http://localhost:5001`
The Web API provides a modern RESTful interface with: The Web API provides a modern RESTful interface with:
- Clean REST endpoints with query parameters - Clean REST endpoints with query parameters
@@ -69,34 +69,34 @@ Direct access to the Visual Studio plugin (use only if Web API is unavailable):
```bash ```bash
# Health check # Health check
curl http://localhost:5000/api/health curl http://localhost:5001/api/health
# Get all projects (returns full file paths) # Get all projects (returns full file paths)
curl http://localhost:5000/api/roslyn/projects curl http://localhost:5001/api/roslyn/projects
# Get solution overview # Get solution overview
curl http://localhost:5000/api/roslyn/solution/overview curl http://localhost:5001/api/roslyn/solution/overview
# Get diagnostics for entire solution # Get diagnostics for entire solution
curl http://localhost:5000/api/roslyn/diagnostics curl http://localhost:5001/api/roslyn/diagnostics
# Get diagnostics for specific file # Get diagnostics for specific file
curl "http://localhost:5000/api/roslyn/diagnostics?filePath=C:/path/to/file.cs" curl "http://localhost:5001/api/roslyn/diagnostics?filePath=C:/path/to/file.cs"
# Get symbol at position (use paths from /projects response) # Get symbol at position (use paths from /projects response)
curl "http://localhost:5000/api/roslyn/symbol?filePath=C:/path/to/file.cs&line=10&column=5" curl "http://localhost:5001/api/roslyn/symbol?filePath=C:/path/to/file.cs&line=10&column=5"
# Find all references # Find all references
curl "http://localhost:5000/api/roslyn/references?filePath=C:/path/to/file.cs&line=18&column=30" curl "http://localhost:5001/api/roslyn/references?filePath=C:/path/to/file.cs&line=18&column=30"
# Search for symbols # Search for symbols
curl "http://localhost:5000/api/roslyn/symbol/search?symbolName=MyClass&kind=class" curl "http://localhost:5001/api/roslyn/symbol/search?symbolName=MyClass&kind=class"
# Get recent history # Get recent history
curl http://localhost:5000/api/history/recent?count=10 curl http://localhost:5001/api/history/recent?count=10
# Get history statistics # Get history statistics
curl http://localhost:5000/api/history/stats curl http://localhost:5001/api/history/stats
``` ```
**IMPORTANT curl syntax rules:** **IMPORTANT curl syntax rules:**
@@ -170,50 +170,50 @@ curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d
```bash ```bash
# Step 1: Check if services are healthy # Step 1: Check if services are healthy
curl http://localhost:5000/api/health curl http://localhost:5001/api/health
# Step 2: Get all projects and their files # Step 2: Get all projects and their files
curl http://localhost:5000/api/roslyn/projects curl http://localhost:5001/api/roslyn/projects
# Response includes: {"data": [{"documents": ["C:/Full/Path/To/File.cs", ...]}]} # Response includes: {"data": [{"documents": ["C:/Full/Path/To/File.cs", ...]}]}
# Step 3: Use the full paths from Step 2 in subsequent queries # Step 3: Use the full paths from Step 2 in subsequent queries
FILE="C:/Users/AJ/Desktop/MyProject/Program.cs" FILE="C:/Users/AJ/Desktop/MyProject/Program.cs"
# Get diagnostics (errors/warnings) for a file # Get diagnostics (errors/warnings) for a file
curl "http://localhost:5000/api/roslyn/diagnostics?filePath=$FILE" curl "http://localhost:5001/api/roslyn/diagnostics?filePath=$FILE"
# Get symbol information at a specific location # Get symbol information at a specific location
curl "http://localhost:5000/api/roslyn/symbol?filePath=$FILE&line=15&column=10" curl "http://localhost:5001/api/roslyn/symbol?filePath=$FILE&line=15&column=10"
# Find all references to that symbol # Find all references to that symbol
curl "http://localhost:5000/api/roslyn/references?filePath=$FILE&line=15&column=10" curl "http://localhost:5001/api/roslyn/references?filePath=$FILE&line=15&column=10"
# Step 4: View your query history # Step 4: View your query history
curl http://localhost:5000/api/history/recent?count=5 curl http://localhost:5001/api/history/recent?count=5
# Step 5: Get statistics about your queries # Step 5: Get statistics about your queries
curl http://localhost:5000/api/history/stats curl http://localhost:5001/api/history/stats
``` ```
### Advanced Query Examples ### Advanced Query Examples
```bash ```bash
# Search for all classes with "Service" in the name # Search for all classes with "Service" in the name
curl "http://localhost:5000/api/roslyn/symbol/search?symbolName=Service&kind=class" curl "http://localhost:5001/api/roslyn/symbol/search?symbolName=Service&kind=class"
# Get solution-wide statistics # Get solution-wide statistics
curl http://localhost:5000/api/roslyn/solution/overview curl http://localhost:5001/api/roslyn/solution/overview
# For complex queries not available as REST endpoints, use POST /query # For complex queries not available as REST endpoints, use POST /query
curl -X POST http://localhost:5000/api/roslyn/query \ curl -X POST http://localhost:5001/api/roslyn/query \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"queryType":"searchcode","symbolName":".*Controller","parameters":{"scope":"classes"}}' -d '{"queryType":"searchcode","symbolName":".*Controller","parameters":{"scope":"classes"}}'
# Build a project # Build a project
curl -X POST "http://localhost:5000/api/roslyn/project/build?projectName=MyProject" curl -X POST "http://localhost:5001/api/roslyn/project/build?projectName=MyProject"
# Add NuGet package # Add NuGet package
curl -X POST "http://localhost:5000/api/roslyn/project/package/add?projectName=MyProject&packageName=Newtonsoft.Json&version=13.0.3" curl -X POST "http://localhost:5001/api/roslyn/project/package/add?projectName=MyProject&packageName=Newtonsoft.Json&version=13.0.3"
``` ```
## Response Format ## Response Format
@@ -253,7 +253,7 @@ All endpoints return JSON in this format:
## Troubleshooting ## Troubleshooting
**"Failed to connect" error:** **"Failed to connect" error:**
1. Check if Web API is running: `curl http://localhost:5000/api/health/ping` 1. Check if Web API is running: `curl http://localhost:5001/api/health/ping`
2. Check if VS Plugin is running: `curl -X POST http://localhost:59123/health -H "Content-Type: application/json" -d "{}"` 2. Check if VS Plugin is running: `curl -X POST http://localhost:59123/health -H "Content-Type: application/json" -d "{}"`
3. Ensure Visual Studio is open with a solution loaded 3. Ensure Visual Studio is open with a solution loaded

53
AGENTS.md
View File

@@ -37,3 +37,56 @@
- Server binds to `http://localhost:59123/` and accepts only POST; CORS is permissive for local tooling. Do not expose externally. - Server binds to `http://localhost:59123/` and accepts only POST; CORS is permissive for local tooling. Do not expose externally.
- Endpoints: `/query` (main), `/health` route exists but still requires POST. - Endpoints: `/query` (main), `/health` route exists but still requires POST.
- Adjust port/paths in `RoslynBridge/Constants/ServerConstants.cs` if needed. - Adjust port/paths in `RoslynBridge/Constants/ServerConstants.cs` if needed.
## Agent Script Usage: rb.ps1 (for AI agents)
This section is for the agent only. Use `rb.ps1` to minimize tokens and speed up local Roslyn queries.
- Location: `rb.ps1` (repo root). Invoke with PowerShell.
- Auto-detects endpoints: prefers Web API (`http://localhost:5001`), falls back to VS plugin (`http://localhost:59123`).
- Output defaults to compact JSON. Use `-Raw` to emit raw response strings, `-Pretty` only for debugging.
- Override detection with `-BaseUrl http://localhost:5001` if needed; `-NoDetect` forces Web API pathing.
Examples (run from repo root):
```powershell
# Health and discovery
powershell -NoProfile -Command .\rb.ps1 health
powershell -NoProfile -Command .\rb.ps1 projects -Raw
powershell -NoProfile -Command .\rb.ps1 overview
# File-specific queries (use full paths from `projects`)
powershell -NoProfile -Command .\rb.ps1 diagnostics -FilePath C:/full/path/File.cs
powershell -NoProfile -Command .\rb.ps1 symbol -FilePath C:/full/path/File.cs -Line 12 -Column 4
powershell -NoProfile -Command .\rb.ps1 references -FilePath C:/full/path/File.cs -Line 12 -Column 4 -Raw
# Symbol search
powershell -NoProfile -Command .\rb.ps1 search -SymbolName Service -Kind class
# Project operations
powershell -NoProfile -Command .\rb.ps1 build -ProjectName MyProject
powershell -NoProfile -Command .\rb.ps1 package-add -ProjectName MyProject -PackageName Newtonsoft.Json -Version 13.0.3
# History (Web API only)
powershell -NoProfile -Command .\rb.ps1 history-recent -Count 10
powershell -NoProfile -Command .\rb.ps1 history-stats
# Compact solution overview summary (uses API-level summary)
powershell -NoProfile -Command .\rb.ps1 solution-overview -Format yaml -Top 5
```
Key behaviors and assumptions:
- Lines are 1-based; columns 0-based.
- Forward slashes `/` are accepted in file paths.
- Prefer `-Raw` to minimize token usage when chaining outputs.
- If Web API is down, commands transparently fall back to the plugin when possible. History endpoints require Web API.
- If auto-detection is ambiguous, set `-BaseUrl` explicitly.
Policy (agent-only):
- Do NOT call `curl`, `Invoke-RestMethod`, or `Invoke-WebRequest` directly to Roslyn Bridge.
- Always invoke `rb.ps1` for all Roslyn-related queries and operations.
- Prefer `-Raw` output and parse only what’s needed to reduce tokens.
- Keep timeouts short unless debugging (`-TimeoutSec` can be raised temporarily).
- Avoid pretty output unless explicitly needed (`-Pretty`).

267
SKILL.md Normal file
View File

@@ -0,0 +1,267 @@
---
name: roslyn-bridge
description: Use this for C# code analysis, querying .NET projects, finding symbols, getting diagnostics, or any Roslyn/semantic analysis tasks using the bridge server
---
# Roslyn Bridge API Guide
Use this guide when accessing the Roslyn Bridge for C# code analysis.
## Architecture
```
┌─────────────┐ REST API ┌────────────────────┐ HTTP ┌─────────────────────┐
│ Claude │ ◄─────────────────► │ Web API (:5001) │ ◄────────────► │ VS Plugin (:59123) │
│ AI │ │ Middleware │ │ Roslyn Bridge │
└─────────────┘ └────────────────────┘ └─────────────────────┘
```
## Recommended: Web API (Port 5001)
**Base URL**: `http://localhost:5001`
The Web API provides a modern RESTful interface with:
- Clean REST endpoints with query parameters
- Full Swagger documentation at `/`
- Request/response history tracking at `/api/history`
- CORS support for web applications
- Better error handling and logging
### Web API Endpoints
**Health & Info:**
- `GET /api/health` - Check health of both Web API and VS plugin
- `GET /api/health/ping` - Simple ping
**Roslyn Operations:**
- `GET /api/roslyn/projects` - Get all projects
- `GET /api/roslyn/solution/overview` - Solution statistics
- `GET /api/roslyn/diagnostics?filePath={path}` - Get errors/warnings
- `GET /api/roslyn/symbol?filePath={path}&line={line}&column={col}` - Get symbol info
- `GET /api/roslyn/references?filePath={path}&line={line}&column={col}` - Find references
- `GET /api/roslyn/symbol/search?symbolName={name}&kind={kind}` - Search symbols
- `POST /api/roslyn/query` - Execute any query (fallback to raw queries)
- `POST /api/roslyn/format` - Format document
- `POST /api/roslyn/project/package/add` - Add NuGet package
- `POST /api/roslyn/project/build` - Build project
**History:**
- `GET /api/history` - All history entries
- `GET /api/history/{id}` - Specific entry
- `GET /api/history/recent?count=50` - Recent entries
- `GET /api/history/stats` - Statistics
- `DELETE /api/history` - Clear history
## Alternative: Direct VS Plugin Access (Port 59123)
**Base URL**: `http://localhost:59123`
Direct access to the Visual Studio plugin (use only if Web API is unavailable):
- **Endpoints**: `/query`, `/health`
- **Method**: POST only
- **Content-Type**: application/json
## ⚠️ CRITICAL: Command Syntax Rules
**ALWAYS use curl with the Bash tool. NEVER pipe curl output to PowerShell.**
### ✅ CORRECT: Using Web API (Recommended)
```bash
# Health check
curl http://localhost:5001/api/health
# Get all projects (returns full file paths)
curl http://localhost:5001/api/roslyn/projects
# Get solution overview
curl http://localhost:5001/api/roslyn/solution/overview
# Get diagnostics for entire solution
curl http://localhost:5001/api/roslyn/diagnostics
# Get diagnostics for specific file
curl "http://localhost:5001/api/roslyn/diagnostics?filePath=C:/path/to/file.cs"
# Get symbol at position (use paths from /projects response)
curl "http://localhost:5001/api/roslyn/symbol?filePath=C:/path/to/file.cs&line=10&column=5"
# Find all references
curl "http://localhost:5001/api/roslyn/references?filePath=C:/path/to/file.cs&line=18&column=30"
# Search for symbols
curl "http://localhost:5001/api/roslyn/symbol/search?symbolName=MyClass&kind=class"
# Get recent history
curl http://localhost:5001/api/history/recent?count=10
# Get history statistics
curl http://localhost:5001/api/history/stats
```
**IMPORTANT curl syntax rules:**
- For GET requests, no `-X GET` needed
- Use quotes around URLs with query parameters
- Forward slashes `/` work in file paths (Windows accepts both `/` and `\`)
- **DO NOT pipe to PowerShell** - the JSON output is already formatted
### Using Direct VS Plugin Access (Fallback)
```bash
# Health check - verify VS plugin is running
curl -X POST http://localhost:59123/health -H "Content-Type: application/json" -d "{}"
# Get projects via POST
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getprojects\"}"
# Get symbol at position
curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getsymbol\",\"filePath\":\"C:\\\\path\\\\to\\\\file.cs\",\"line\":10,\"column\":5}"
```
**Note:** In POST requests to VS plugin, escape backslashes: `\\\\` becomes `\\` in JSON
## Quick Reference: All Endpoints
### Query Endpoints
| Endpoint | Required Fields | Optional Fields | Description |
|----------|----------------|-----------------|-------------|
| `getprojects` | - | - | Get all projects in the solution |
| `getdocument` | `filePath` | - | Get document information for a specific file |
| `getsymbol` | `filePath`, `line`, `column` | - | Get symbol information at a specific position |
| `getsemanticmodel` | `filePath` | - | Verify semantic model availability (not serializable) |
| `getsyntaxtree` | `filePath` | - | Get the syntax tree (source code) for a file |
| `getdiagnostics` | - | `filePath` | Get compilation errors and warnings |
| `findreferences` | `filePath`, `line`, `column` | - | Find all references to a symbol |
| `findsymbol` | `symbolName` | `parameters.kind` | Find symbols by name (supports filtering by kind) |
| `gettypemembers` | `symbolName` | `parameters.includeInherited` | Get all members of a type |
| `gettypehierarchy` | `symbolName` | `parameters.direction` | Get base types or derived types |
| `findimplementations` | `symbolName` OR `filePath`+`line`+`column` | - | Find implementations of an interface/abstract member |
| `getnamespacetypes` | `symbolName` | - | Get all types in a namespace |
| `getcallhierarchy` | `filePath`, `line`, `column` | `parameters.direction` | Get callers or callees of a method |
| `getsolutionoverview` | - | - | Get high-level solution statistics |
| `getsymbolcontext` | `filePath`, `line`, `column` | - | Get contextual information about a symbol's location |
| `searchcode` | `symbolName` (regex) | `parameters.scope` | Search for code patterns using regex |
### Editing Endpoints
| Endpoint | Required Fields | Optional Fields | Description |
|----------|----------------|-----------------|-------------|
| `formatdocument` | `filePath` | - | Format a document according to coding style |
| `organizeusings` | `filePath` | - | Sort and remove unused using statements |
| `renamesymbol` | `filePath`, `line`, `column`, `parameters.newName` | - | Rename a symbol across the solution |
| `addmissingusing` | `filePath`, `line`, `column` | - | Add missing using statement for a symbol |
| `applycodefix` | `filePath`, `line`, `column` | - | Apply available code fixes at a position |
### Project Operation Endpoints
| Endpoint | Required Fields | Optional Fields | Description |
|----------|----------------|-----------------|-------------|
| `addnugetpackage` | `projectName`, `packageName` | `version` | Add a NuGet package to a project |
| `removenugetpackage` | `projectName`, `packageName` | - | Remove a NuGet package from a project |
| `buildproject` | `projectName` | `configuration` | Build a project or solution |
| `cleanproject` | `projectName` | - | Clean build output |
| `restorepackages` | `projectName` | - | Restore NuGet packages |
| `createdirectory` | `directoryPath` | - | Create a new directory |
## Common Workflow Examples
### Typical Code Analysis Workflow
```bash
# Step 1: Check if services are healthy
curl http://localhost:5001/api/health
# Step 2: Get all projects and their files
curl http://localhost:5001/api/roslyn/projects
# Response includes: {"data": [{"documents": ["C:/Full/Path/To/File.cs", ...]}]}
# Step 3: Use the full paths from Step 2 in subsequent queries
FILE="C:/Users/AJ/Desktop/MyProject/Program.cs"
# Get diagnostics (errors/warnings) for a file
curl "http://localhost:5001/api/roslyn/diagnostics?filePath=$FILE"
# Get symbol information at a specific location
curl "http://localhost:5001/api/roslyn/symbol?filePath=$FILE&line=15&column=10"
# Find all references to that symbol
curl "http://localhost:5001/api/roslyn/references?filePath=$FILE&line=15&column=10"
# Step 4: View your query history
curl http://localhost:5001/api/history/recent?count=5
# Step 5: Get statistics about your queries
curl http://localhost:5001/api/history/stats
```
### Advanced Query Examples
```bash
# Search for all classes with "Service" in the name
curl "http://localhost:5001/api/roslyn/symbol/search?symbolName=Service&kind=class"
# Get solution-wide statistics
curl http://localhost:5001/api/roslyn/solution/overview
# For complex queries not available as REST endpoints, use POST /query
curl -X POST http://localhost:5001/api/roslyn/query \
-H "Content-Type: application/json" \
-d '{"queryType":"searchcode","symbolName":".*Controller","parameters":{"scope":"classes"}}'
# Build a project
curl -X POST "http://localhost:5001/api/roslyn/project/build?projectName=MyProject"
# Add NuGet package
curl -X POST "http://localhost:5001/api/roslyn/project/package/add?projectName=MyProject&packageName=Newtonsoft.Json&version=13.0.3"
```
## Response Format
All endpoints return JSON in this format:
**Success:**
```json
{
"success": true,
"message": "Optional message",
"data": { /* Response data varies by endpoint */ },
"error": null
}
```
**Error:**
```json
{
"success": false,
"message": null,
"data": null,
"error": "Error description"
}
```
## Important Notes
- Line numbers are **1-based** (first line is 1)
- Column numbers are **0-based** (first column is 0)
- **Use full paths from `/api/roslyn/projects` response** in other endpoints
- Forward slashes `/` work in file paths (Windows accepts both `/` and `\`)
- Both the Web API (port 5000) and VS Plugin (port 59123) must be running
- All workspace modifications use VS threading model
- Request history is automatically tracked in the Web API
## Troubleshooting
**"Failed to connect" error:**
1. Check if Web API is running: `curl http://localhost:5001/api/health/ping`
2. Check if VS Plugin is running: `curl -X POST http://localhost:59123/health -H "Content-Type: application/json" -d "{}"`
3. Ensure Visual Studio is open with a solution loaded
**"vsPluginStatus": "Disconnected":**
- The VS Plugin (port 59123) is not running
- Open Visual Studio and ensure the RoslynBridge extension is loaded
**Empty or null data:**
- Ensure you're using the correct file paths from `/api/roslyn/projects`
- Verify line/column numbers are within the file bounds
- Check that the file is part of the currently open VS solution