diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 9ea49fc..06c8633 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,7 +7,7 @@ { "name": "opentrace", "source": "./", - "description": "System architecture exploration and incident investigation using OpenTrace's knowledge graph" + "description": "Explore code structure and dependencies across your organization's indexed projects using OpenTrace's code graphs" } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index a5709d1..99fc811 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "opentrace", - "version": "0.0.6", - "description": "System architecture exploration and incident investigation using OpenTrace's knowledge graph", + "version": "0.1.0", + "description": "Explore code structure and dependencies across your organization's indexed projects using OpenTrace's code graphs", "author": { "name": "OpenTrace Team" }, @@ -10,8 +10,8 @@ "repository": "https://github.com/opentrace/claude-code", "keywords": [ "architecture", - "observability", - "incident-response", + "code-graph", + "dependencies", "knowledge-graph", "mcp" ], @@ -30,7 +30,7 @@ ], "PreToolUse": [ { - "matcher": "mcp__.*(?i)opentrace.*(traverse_dependencies|traverse_incoming|traverse_outgoing|get_neighbors)", + "matcher": "mcp__.*(?i)opentrace.*traverse_project", "hooks": [ { "type": "command", diff --git a/CLAUDE.md b/CLAUDE.md index 1cac77c..43b9920 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## What This Repository Is -This is the **OpenTrace Claude Code Plugin** — a Claude Code plugin that connects Claude to OpenTrace's knowledge graph for system architecture exploration and incident investigation. It is distributed via the Claude Code plugin marketplace. +This is the **OpenTrace Claude Code Plugin** — a Claude Code plugin that connects Claude to OpenTrace's project code graphs for exploring code structure, dependencies, and source across an organization's indexed projects. It is distributed via the Claude Code plugin marketplace. ## Architecture @@ -12,7 +12,7 @@ This is the **OpenTrace Claude Code Plugin** — a Claude Code plugin that conne - `.claude-plugin/plugin.json` — Plugin manifest: name, version, MCP server references, and hook definitions - `.claude-plugin/marketplace.json` — Marketplace metadata for plugin discovery -- `mcp-servers/opentrace.json` — MCP server configuration pointing to `https://api.opentrace.ai/mcp/v1` +- `mcp-servers/opentrace.json` — MCP server configuration pointing to `https://api.opentrace.ai/mcp/v1/projects` - `hooks/` — Plugin hooks (see below) ### Plugin Hooks @@ -22,8 +22,7 @@ Hooks are defined in `.claude-plugin/plugin.json` and reference scripts in `hook | Hook | Trigger | Purpose | |------|---------|---------| | `SessionStart` | Every session | Injects system context telling Claude that OpenTrace is available and when to use it | -| `PreToolUse` (traversal) | Traversal/neighbor tool calls | Guardrail: warns when `maxDepth >= 3` with no filters to prevent oversized results | -| `PostToolUse` (navigation) | After any OpenTrace tool call | Prompt-based hook: suggests logical next exploration steps based on which tool was just used | +| `PreToolUse` (traversal) | `traverse_project` tool calls | Guardrail: warns when `max_depth >= 3` with no `rel_type` filter to prevent oversized results | Hook scripts use `${CLAUDE_PLUGIN_ROOT}` to resolve paths relative to the plugin installation directory. @@ -68,5 +67,4 @@ There is no automated test suite. Testing is manual: - Hook scripts must output valid JSON to stdout. Return `{}` for silent pass-through. - The `PreToolUse` guardrail pattern: read tool input from stdin via `jq`, check parameters, output structured JSON with `additionalContext` warnings or empty `{}`. -- The `PostToolUse` navigation pattern: prompt-based hook (`.txt` file) that provides contextual suggestions without blocking. - Plugin version is in `.claude-plugin/plugin.json` — bump it when releasing changes. diff --git a/README.md b/README.md index 2ea8667..155c7cc 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # OpenTrace Claude Code Plugin -Connect Claude Code to your organization's knowledge graph for architecture exploration and incident investigation. +Connect Claude Code to your organization's indexed projects to explore code structure, dependencies, and source across repositories. ## Installation @@ -14,67 +14,62 @@ Connect Claude Code to your organization's knowledge graph for architecture expl /plugin install opentrace ``` -3. **Authenticate**: On first use, you'll be prompted to sign in via your browser. +3. **Authenticate**: On first use, you'll be prompted to sign in via your browser. After signing in, you'll see an organization-selection page — pick the org whose projects you want to explore. ## Usage Examples -### 1. Discover System Architecture +### 1. Discover Available Projects ``` -Use discover_architecture to explore my system starting from payment-service +List the projects I can explore with OpenTrace ``` -Maps dependencies, identifies architectural patterns, and provides insights about a component's role. +Shows every project your organization has indexed, so you can pick one to dig into. -### 2. Analyze Dependencies +### 2. Find a Definition ``` -Use dependency_analysis to understand how payment-service connects to other components +Find where PaymentProcessor is defined in the billing project ``` -Maps upstream dependencies (what it relies on) and downstream dependents (what relies on it). +Searches the project's code graph and pinpoints the file and symbol — even if the repo isn't checked out locally. -### 3. Search the Knowledge Graph +### 3. Trace Callers and Dependencies ``` -Search for all services related to authentication +What calls the validate_invoice function in the billing project? ``` -or use the tools directly: +Traverses the code graph to map callers, dependents, and dependencies of any class, function, or file. -``` -Use search_nodes to find services matching "payment" -Use query_nodes to list all Service nodes -``` - -### 4. Impact Analysis +### 4. Read Remote Source ``` -Use impact_analysis to check what would be affected if we modify billing-api +Fetch the source of src/billing/processor.py from the billing project ``` -Identifies all dependent components and highlights critical paths. +Returns the full file content straight from the project's indexed bundle — no clone or checkout needed. ## Available Tools -| Category | Tools | -|----------|-------| -| **Discovery** | `search_nodes`, `query_nodes`, `get_node`, `find_similar_nodes` | -| **Traversal** | `traverse_dependencies`, `traverse_incoming`, `traverse_outgoing`, `get_neighbors` | -| **Analysis** | `find_path`, `get_node_statistics` | -| **Source** | `load_source` (GitHub/GitLab integration) | - -**Analysis Prompts**: `discover_architecture`, `impact_analysis`, `dependency_analysis` +| Tool | Purpose | +|------|---------| +| `list_projects` | List the projects indexed for your organization | +| `query_project` | Full-text search for files, classes, and functions in a project | +| `traverse_project` | Traverse the code graph from a node (incoming, outgoing, or both) | +| `get_project_node` | Get the details of a single node | +| `fetch_project_file` | Fetch the full source of a file in a project | ## Troubleshooting | Problem | Solution | |---------|----------| | Authentication failed | Ensure you have an active OpenTrace account and are a member of an organization | -| No results found | Your knowledge graph may not have data yet, or check component name spelling | +| No results found | The project may not be indexed yet, or check the name spelling | +| First query is slow or times out | The project bundle loads lazily on first access — retry the query once | | Connection errors | Check internet connection; verify https://api.opentrace.ai is accessible | ## Links - [OpenTrace Documentation](https://docs.opentrace.ai) -- [GitHub Issues](https://github.com/opentrace/insight-claude-plugin/issues) +- [GitHub Issues](https://github.com/opentrace/claude-code/issues) diff --git a/agents/explore.md b/agents/explore.md index 1d0cede..9e29566 100644 --- a/agents/explore.md +++ b/agents/explore.md @@ -1,20 +1,20 @@ --- name: explore description: | - OpenTrace-aware architecture explorer for multi-step system investigation. + OpenTrace-aware code explorer for multi-step investigation of indexed projects. Prefer this agent over the built-in Explore when the task involves: - - Understanding service dependencies or upstream/downstream relationships - - Cross-service or cross-repo investigation - - Dependency mapping, blast radius analysis, or impact assessment - - Incident investigation, outage diagnosis, or error propagation tracing - - Discovering system topology, integration points, or deployment architecture - This agent combines local codebase tools with OpenTrace's knowledge graph - to answer architecture questions that span beyond the current repository. + - Exploring the code graph of a project indexed in OpenTrace + - Finding definitions, callers, or dependencies of classes and functions — + including in repositories that are not checked out locally + - Dependency mapping or blast radius analysis at the code level + - Comparing code structure across several indexed projects + This agent combines local codebase tools with OpenTrace's project code graphs + to answer code-structure questions that span beyond the current repository. tools: Bash, Read, Glob, Grep, WebFetch, WebSearch, mcp__plugin_opentrace_opentrace__* color: cyan --- -You are an expert system architecture explorer with access to two complementary toolsets: **local codebase tools** and **OpenTrace knowledge graph tools**. Your job is to answer architecture questions, map dependencies, investigate incidents, and trace how components connect across the system. +You are an expert code explorer with access to two complementary toolsets: **local codebase tools** and **OpenTrace project code graph tools**. Your job is to answer code-structure questions, map dependencies, and trace how classes, functions, and files connect — within one indexed project or across several. ## Tool Selection @@ -22,71 +22,72 @@ Use the right tool for the job: | Question | Tool | |----------|------| -| What's in this file / function / class? | Read, Grep, Glob | -| What services depend on this one? | OpenTrace: `traverse_incoming`, `get_neighbors` | -| What does this service call downstream? | OpenTrace: `traverse_outgoing`, `traverse_dependencies` | -| How are two services connected? | OpenTrace: `find_path` | -| What exists in the system matching X? | OpenTrace: `search_nodes`, `query_nodes` | -| What's the shape of the overall system? | OpenTrace: `get_node_statistics` | -| What does a specific node represent? | OpenTrace: `get_node` | -| What nodes are similar to this one? | OpenTrace: `find_similar_nodes` | -| What code does a remote service have? | OpenTrace: `load_source`, `load_source_from_node` | +| What's in this file / function / class (locally)? | Read, Grep, Glob | +| What projects can I explore? | OpenTrace: `list_projects` | +| Where is X defined in a project? | OpenTrace: `query_project` | +| What calls this function / depends on this file? | OpenTrace: `traverse_project` with `direction: incoming` | +| What does this symbol call or depend on? | OpenTrace: `traverse_project` with `direction: outgoing` | +| What does a specific node represent? | OpenTrace: `get_project_node` | +| What's the source of a file in a remote project? | OpenTrace: `fetch_project_file` | | What's happening on the web / in docs? | WebFetch, WebSearch | -**Default to local tools** for anything inside the current codebase. **Use OpenTrace** when the question touches services, infrastructure, or code outside this repo. +**Default to local tools** for anything inside the current codebase. **Use OpenTrace** when the question touches an indexed project — especially a repo that is not checked out locally. -## OpenTrace Traversal Best Practices +Graph vocabulary: node types are `Repo`, `Directory`, `File`, `Class`, `Function`, and `Dependency`; relationships are `DEFINES`, `DEPENDS_ON`, `CALLS`, and `DEFINED_IN`. Node ids are path-shaped: the repo root is `{org}/{repo}`, directories and files are `{org}/{repo}/{path}`, and symbols are `{org}/{repo}/{path}::{symbol}`. -- **Start shallow**: Use `maxDepth: 1` first, then increase only if needed. -- **Apply filters**: Use `edgeTypes` or `nodeTypes` to narrow results (e.g., `edgeTypes: ["CALLS"]` to see only call relationships). -- **Inspect before diving deeper**: After a traversal, use `get_node` on the most interesting result before doing another traversal from it. -- **Avoid oversized queries**: Never use `maxDepth >= 3` without filters — the result set becomes unmanageable. +## Project Selection (always step 0) + +Every tool except `list_projects` requires a `project_id`: + +1. Call `list_projects` to see what is available. +2. If the user named a project, match it against the returned names/slugs. Otherwise try matching the current directory's git repo name. Otherwise ask which project to use. +3. **Remember the chosen `project_id` for the rest of the task** — do not re-list projects on every call. + +The first query against a project triggers a lazy bundle load server-side, so it may be slow or time out. Retry once before concluding the project is unavailable. + +## Traversal Best Practices + +- **Start shallow**: Use `max_depth: 1` first, then increase only if needed (default is 3, max 10). +- **Filter by relationship**: Set `rel_type` to a single relationship (e.g. `CALLS`) to narrow results. +- **Inspect before diving deeper**: After a traversal, use `get_project_node` on the most interesting result before doing another traversal from it. +- **Avoid oversized queries**: Never use `max_depth >= 3` without a `rel_type` filter — the result set becomes unmanageable. +- **Orient from the root**: In an unfamiliar project, traverse from the repo root node (`{org}/{repo}`) with `direction: outgoing` and `max_depth: 1` to see the top-level structure. There is no statistics tool. ## Auto-Follow-Up Chain After each OpenTrace tool call, automatically pick the best follow-up to deepen your understanding. Do not ask the user what to do next — just continue exploring: -- `search_nodes` / `query_nodes` → `get_neighbors` on the most relevant result -- `get_node` → `get_neighbors` or `traverse_incoming` / `traverse_outgoing` -- `get_neighbors` → `traverse_dependencies` to go deeper, or `find_path` between interesting neighbors -- `traverse_dependencies` / `traverse_incoming` / `traverse_outgoing` → `get_node` on the most important result, or `find_path` between notable endpoints -- `find_path` → `get_node` on the most critical intermediate node -- `get_node_statistics` → `search_nodes` to explore the most connected node types -- `find_similar_nodes` → `get_neighbors` to compare connection patterns -- `load_source` / `load_source_from_node` → no follow-up needed +- `list_projects` → `query_project` or `traverse_project` on the selected project +- `query_project` → `get_project_node` on the most relevant hit, or `traverse_project` from it +- `get_project_node` → `traverse_project` from the node (`max_depth: 1` shows direct neighbors — the node itself comes back without them) +- `traverse_project` → `get_project_node` on the most important result, or `fetch_project_file` if it's a File node you need to read +- `fetch_project_file` → no follow-up needed Do not re-call the tool that just ran. Stop exploring when the user's question is fully answered. ## Common Exploration Patterns ### Dependency Mapping -1. `search_nodes` to find the target service -2. `get_neighbors` to see direct connections -3. `traverse_incoming` for upstream dependents, `traverse_outgoing` for downstream dependencies -4. `get_node` on critical dependencies for detail +1. `query_project` to find the target file, class, or function +2. `traverse_project` with `direction: incoming` for what depends on it; `direction: outgoing` for what it depends on +3. `get_project_node` on critical dependencies for detail ### Blast Radius Analysis -1. `search_nodes` to find the service or component -2. `traverse_incoming` with `maxDepth: 2` to find everything that depends on it -3. `get_node` on each upstream consumer to assess impact -4. `find_path` between the failing service and user-facing endpoints - -### Path Tracing -1. `search_nodes` to find both endpoints -2. `find_path` between them -3. `get_node` on intermediate hops to understand the route - -### Incident Investigation -1. `search_nodes` to find the affected service -2. `get_neighbors` to see what it connects to -3. `traverse_outgoing` to check downstream dependencies for failures -4. `traverse_incoming` to identify affected upstream callers -5. `load_source` if you need to inspect the service's code +1. `query_project` to find the symbol or file being changed +2. `traverse_project` with `direction: incoming` and `max_depth: 2` to find everything that calls or depends on it (use `rel_type: CALLS` to focus on callers) +3. `get_project_node` on each dependent to assess impact + +### Cross-Project Comparison +1. `list_projects` to identify the projects to compare +2. Run the same `query_project` against each project's `project_id` +3. `traverse_project` / `fetch_project_file` in each to compare structure or implementations side by side + +There is no path-finding tool. To approximate a connection between two nodes, traverse outward from both (shallow, filtered) and look for overlap in the results. ## Output Guidelines - Always tell the user which tools you're using and why. - When presenting OpenTrace results, summarize the key findings — don't dump raw JSON. -- If you find relevant source code in other repos via `load_source`, show the relevant snippets. +- If you fetch relevant source via `fetch_project_file`, show the relevant snippets, not the whole file. - When mapping dependencies, present them as a clear list or hierarchy, not a wall of text. - If the exploration reveals something unexpected or important, highlight it explicitly. diff --git a/cspell.json b/cspell.json index 9cd6098..a25f1fa 100644 --- a/cspell.json +++ b/cspell.json @@ -17,11 +17,6 @@ "hookEventName", "additionalContext", "systemMessage", - "maxDepth", - "edgeTypes", - "nodeTypes", - "edgeFilter", - "nodeFilter", "mcpServers", "pipefail", "CURDIR", @@ -31,9 +26,7 @@ "reinstall", "tooluse", "PreToolUse", - "PostToolUse", "SessionStart", - "oauths", "BASEEOF", "toolsets" ] diff --git a/hooks/pre-tool-use-traversal/script.sh b/hooks/pre-tool-use-traversal/script.sh index bd693a4..52b2624 100755 --- a/hooks/pre-tool-use-traversal/script.sh +++ b/hooks/pre-tool-use-traversal/script.sh @@ -1,8 +1,8 @@ #!/usr/bin/env bash # -# PreToolUse guardrail for OpenTrace traversal/neighbor tools. -# Warns when maxDepth >= 3 with no filters — a common mistake that -# returns massive result sets and can hit MCP size limits. +# PreToolUse guardrail for the OpenTrace traverse_project tool. +# Warns when max_depth >= 3 with no rel_type filter — a common mistake +# that returns massive result sets and can hit MCP size limits. # # Reads the tool input JSON from stdin. Outputs structured JSON: # - Warning via additionalContext when risky params detected @@ -20,25 +20,20 @@ if [ -z "$tool_input" ]; then exit 0 fi -# Extract maxDepth (default 1 if not set) -max_depth=$(echo "$tool_input" | jq -r '.maxDepth // 1') - -# Check for any filter parameters that constrain the traversal -has_filters=$(echo "$tool_input" | jq ' - (has("edgeTypes") and (.edgeTypes | length > 0)) or - (has("nodeTypes") and (.nodeTypes | length > 0)) or - (has("filters") and (.filters | length > 0)) or - (has("nodeFilter") and (.nodeFilter | length > 0)) or - (has("edgeFilter") and (.edgeFilter | length > 0)) or - (has("limit") and .limit != null) +# Extract max_depth (the server defaults to 3 when absent) +max_depth=$(echo "$tool_input" | jq -r '.max_depth // 3') + +# rel_type is the only narrowing parameter on traverse_project +has_filter=$(echo "$tool_input" | jq ' + has("rel_type") and (.rel_type | type == "string" and length > 0) ') -if [ "$max_depth" -ge 3 ] 2>/dev/null && [ "$has_filters" = "false" ]; then +if [ "$max_depth" -ge 3 ] 2>/dev/null && [ "$has_filter" = "false" ]; then cat << 'EOF' { "hookSpecificOutput": { "hookEventName": "PreToolUse", - "additionalContext": "WARNING: This traversal has maxDepth >= 3 with no filters. Deep unfiltered traversals often return very large result sets that hit MCP size limits and produce noisy output. Consider: (1) reducing maxDepth to 1 or 2 for initial exploration, (2) adding edgeTypes or nodeTypes filters to narrow results, or (3) using limit to cap the number of returned nodes. Start shallow, then go deeper on interesting paths." + "additionalContext": "WARNING: This traversal has max_depth >= 3 (the server default) with no rel_type filter. Deep unfiltered traversals often return very large result sets that hit MCP size limits and produce noisy output. Consider: (1) setting max_depth to 1 or 2 for initial exploration, or (2) setting rel_type to a single relationship (e.g. CALLS, DEFINES, DEPENDS_ON, DEFINED_IN) to narrow results. Start shallow, then go deeper on interesting paths." } } EOF diff --git a/hooks/session-start/script.sh b/hooks/session-start/script.sh index 00d1af0..83ee9d7 100755 --- a/hooks/session-start/script.sh +++ b/hooks/session-start/script.sh @@ -17,9 +17,9 @@ if [[ " ${missing_deps[*]} " == *" jq "* ]]; then { "hookSpecificOutput": { "hookEventName": "SessionStart", - "additionalContext": "You have access to OpenTrace, a knowledge graph that maps the user's system architecture, service relationships, and project metadata. Use your local tools (Read, Grep, Glob, etc.) for anything within the current codebase. Use OpenTrace when you need context beyond the local project — such as discovering upstream/downstream services, finding related classes or endpoints in other repositories, understanding deployment topology, looking up issues and tickets, or tracing how components connect across the system. When a question touches anything outside the current repo, consider checking OpenTrace. Always inform the user when you are about to use OpenTrace and briefly explain what you are looking for." + "additionalContext": "You have access to OpenTrace, which serves code graphs for the projects your organization has indexed. Use your local tools (Read, Grep, Glob, etc.) for anything within the current codebase. Use OpenTrace when a question concerns an indexed project — especially a repository that is not checked out locally — or when comparing code across several projects. Start with list_projects to see what is available, pick the project that matches the user's request (or the current repo), and remember its project_id for the rest of the task. Always inform the user when you are about to use OpenTrace and briefly explain what you are looking for." }, - "systemMessage": "\n\n\tOpenTrace is active — system architecture insights are available.\n\n\t⚠ Missing dependencies: ${install_list}. Install with: brew install ${install_list} (macOS) or sudo apt install ${install_list} (Linux)." + "systemMessage": "\n\n\tOpenTrace is active — project code graphs are available.\n\n\t⚠ Missing dependencies: ${install_list}. Install with: brew install ${install_list} (macOS) or sudo apt install ${install_list} (Linux)." } FALLBACK exit 0 @@ -69,19 +69,7 @@ if [ -n "$access_token" ] && [ "$HAS_CURL" = true ]; then " (role: " + (."user.org.role" // "unknown") + ")" + "\n\nSource Code Access:" + - "\nUse load_source and load_source_from_node to fetch source code from: " + - ([."user.oauths"[]?.name] | - if length == 0 then "no providers connected." - else join(", ") + "." end) + - " This is useful for reading code in other services, reviewing implementations across repos, or understanding how external dependencies work — without the user needing to clone the repo locally." + - - "\n\nOrganization Integrations:" + - "\nThe following data sources are connected and enrich the OpenTrace knowledge graph:" + - "\n" + ([."org.integrations"[]? | - "- " + .name + " [" + .data_type + "]"] | - if length == 0 then "- none" - else join("\n") end) + - "\nSource integrations provide repository and code data; trace integrations provide request flow and latency data; issue tracking integrations provide ticket and project context; observability integrations provide dashboard and alerting context." + "\nUse fetch_project_file to read the full source of any File node in an indexed project. The content is served from the project'\''s own bundle — no source-hosting integration or extra authentication is needed. This is useful for reading code in repositories the user has not checked out locally." ' 2>/dev/null) || true fi fi @@ -90,29 +78,30 @@ fi # 3. Base additionalContext — OpenTrace usage instructions for Claude # --------------------------------------------------------------------------- read -r -d '' base_context << 'BASEEOF' || true -You have access to OpenTrace, a knowledge graph that maps the user's system architecture, service relationships, and project metadata. Use your local tools (Read, Grep, Glob, etc.) for anything within the current codebase. Use OpenTrace when you need context beyond the local project — such as discovering upstream/downstream services, finding related classes or endpoints in other repositories, understanding deployment topology, looking up issues and tickets, or tracing how components connect across the system. When a question touches anything outside the current repo, consider checking OpenTrace. Always inform the user when you are about to use OpenTrace and briefly explain what you are looking for. +You have access to OpenTrace, which serves code graphs for the projects your organization has indexed. Each project graph maps a repository's code structure: Repo, Directory, File, Class, Function, and Dependency nodes, connected by DEFINES, DEPENDS_ON, CALLS, and DEFINED_IN relationships. Use your local tools (Read, Grep, Glob, etc.) for anything within the current codebase. Use OpenTrace when a question concerns an indexed project — especially a repository that is not checked out locally — or when comparing code across several projects. Always inform the user when you are about to use OpenTrace and briefly explain what you are looking for. -Proactively query OpenTrace (search_nodes, get_neighbors, traverse_dependencies) before starting work when the user's message: -- References named services, APIs, or external integrations -- Mentions system components, pipelines, or infrastructure -- Involves incidents, outages, production issues, or on-call concerns -- Asks about dependencies, impact, blast radius, or upstream/downstream effects -- Involves editing code that integrates with external services or shared middleware +Five tools are available: list_projects, query_project (full-text search), traverse_project (BFS traversal), get_project_node (node details), and fetch_project_file (full file source). Every tool except list_projects requires a project_id. -When about to edit files in shared integration or infrastructure paths (e.g. directories named integrations, middleware, connectors, adapters, clients, providers, gateway, or similar) that are NOT test files or mocks, consider querying OpenTrace (search_nodes, get_neighbors, traverse_dependencies) first to understand the blast radius — which services depend on this component and what downstream effects the change may have. +Workflow: +1. Call list_projects first to see the available projects. +2. Select a project: if the user named one, match it against the returned names/slugs; otherwise try matching the current directory's git repo name; otherwise ask the user. +3. Remember the chosen project_id for the rest of the task — do not re-list projects on every call. + +To orient yourself in an unfamiliar project, traverse from the repo root node (its id is `{org}/{repo}`) with direction: outgoing and max_depth: 1 to see the top-level structure. Node ids are path-shaped: directories and files are `{org}/{repo}/{path}`, and symbols are `{org}/{repo}/{path}::{symbol}`. + +The first query against a project triggers a lazy bundle load server-side, so it may be slow or time out. Retry once before concluding the project is unavailable. After receiving OpenTrace tool results, automatically call the most useful follow-up tool to deepen the exploration rather than stopping to ask the user what to do next. Choose the follow-up based on which tool just ran: -- search_nodes or query_nodes → call get_neighbors on the most relevant node -- get_node → call get_neighbors or traverse_incoming/traverse_outgoing to understand the node's role -- get_neighbors → call traverse_dependencies to go deeper, or find_path between two interesting neighbors -- traverse_dependencies, traverse_incoming, or traverse_outgoing → call get_node for details on the most relevant result, or find_path between notable endpoints -- find_path → call get_node to inspect the most critical intermediate node -- get_node_statistics → call search_nodes to explore the most connected node types -- find_similar_nodes → call get_neighbors to compare connection patterns -- load_source or load_source_from_node → no follow-up needed +- list_projects → query_project or traverse_project on the selected project +- query_project → get_project_node on the most relevant hit, or traverse_project from it +- get_project_node → traverse_project from the node (max_depth: 1 shows its direct neighbors) +- traverse_project → get_project_node for details on the most relevant result, or fetch_project_file if the result is a File node you need to read +- fetch_project_file → no follow-up needed Do not re-call the tool that just ran. Pick the single best follow-up. If the user's question has already been fully answered, stop and present the answer instead of exploring further. -For multi-step architecture exploration — such as dependency mapping, blast radius analysis, cross-service investigation, or incident diagnosis — prefer delegating to the `opentrace:explore` agent (via the Task tool with subagent_type) rather than making direct OpenTrace calls or using the built-in Explore agent. The `opentrace:explore` agent has full access to both local codebase tools and OpenTrace's knowledge graph, with built-in traversal best practices and auto-follow-up logic. Use it whenever the question spans beyond the current repository or requires chaining multiple OpenTrace tool calls. +When about to edit code that other parts of a project depend on (shared utilities, widely-imported modules, public interfaces), consider checking the code-level blast radius first: traverse_project from the symbol or file with direction: incoming to see what calls or depends on it. + +For multi-step exploration — such as dependency mapping, blast radius analysis, or cross-project comparison — prefer delegating to the `opentrace:explore` agent (via the Task tool with subagent_type) rather than making direct OpenTrace calls or using the built-in Explore agent. The `opentrace:explore` agent has full access to both local codebase tools and OpenTrace's project graphs, with built-in traversal best practices and auto-follow-up logic. Use it whenever the question spans beyond the current repository or requires chaining multiple OpenTrace tool calls. BASEEOF # --------------------------------------------------------------------------- @@ -125,11 +114,11 @@ else fi if [ -n "$user_org_info" ]; then - system_msg=$(printf '\n\n\tOpenTrace is active — system architecture insights are available.\n\t%s' "$user_org_info") + system_msg=$(printf '\n\n\tOpenTrace is active — project code graphs are available.\n\t%s' "$user_org_info") elif [ "$HAS_CURL" = false ]; then - system_msg=$'\n\n\tOpenTrace is active — system architecture insights are available.\n\n\t⚠ Missing dependency: curl. Install with: brew install curl (macOS) or sudo apt install curl (Linux).' + system_msg=$'\n\n\tOpenTrace is active — project code graphs are available.\n\n\t⚠ Missing dependency: curl. Install with: brew install curl (macOS) or sudo apt install curl (Linux).' else - system_msg=$'\n\n\tOpenTrace is active — system architecture insights are available.' + system_msg=$'\n\n\tOpenTrace is active — project code graphs are available.' fi # --------------------------------------------------------------------------- diff --git a/mcp-servers/opentrace.json b/mcp-servers/opentrace.json index d38c4c9..5b5d23a 100644 --- a/mcp-servers/opentrace.json +++ b/mcp-servers/opentrace.json @@ -1,7 +1,7 @@ { "opentrace": { "type": "http", - "url": "https://api.opentrace.ai/mcp/v1", - "description": "OpenTrace knowledge graph and investigation tools" + "url": "https://api.opentrace.ai/mcp/v1/projects", + "description": "OpenTrace project code graphs — explore code structure and dependencies across indexed projects" } }