176 lines
9.8 KiB
Markdown
176 lines
9.8 KiB
Markdown
---
|
|
name: nim-mcp-tools
|
|
description: 'Use for Nim symbol navigation, diagnostics, and type resolution. MANDATORY: Use specialized MCP tools (nimFindSymbols, nimFindReferences, nimListSymbols, nimCheckFile, nimCheckProject, nimFindTypeDefinition) first; fall back to grep only on error or user confirmation.'
|
|
---
|
|
|
|
# Nim MCP Tools
|
|
|
|
## Core Mandate
|
|
|
|
AI agents MUST prefer specialized MCP tools over general-purpose instruments (grep, shell commands, `read_file` with manual parsing) for all Nim symbol-related and Nim diagnostics tasks. This is critical for:
|
|
|
|
1. **Token Efficiency**: MCP tools return structured, relevant data, avoiding large file reads or noisy grep outputs.
|
|
2. **Precision**: These tools understand Nim semantics (scopes, imports, overloads) which string-based search cannot.
|
|
|
|
## Activation Rule
|
|
|
|
If the user asks to find, rename, remove, audit, update, standardize naming, or fix issues/project of a Nim symbol or its usages, this skill MUST be used first and the workflow must start with the Nim MCP symbol tools.
|
|
|
|
If the user asks to check a single Nim file for errors, warnings, hints, diagnostics, issues, problems, or compiler feedback, this skill MUST be used first and the workflow must start with `nimCheckFile`.
|
|
|
|
If the user asks to check a Nim project for errors, warnings, hints, diagnostics, issues, problems, compiler feedback, or to "fix" it, this skill MUST be used first and the workflow must start with `nimCheckProject`.
|
|
|
|
If the user asks to determine where a symbol comes from, what type it is, what its fields are (including private ones), or resolve a symbol's type definition, this skill MUST be used first and the workflow must start with `nimFindTypeDefinition`.
|
|
|
|
This applies to requests phrased as:
|
|
|
|
- "find all usages/references of `Foo`"
|
|
- "remove all definitions of and references to `Foo`"
|
|
- "rename `Foo` everywhere"
|
|
- "standardize naming for `Foo`"
|
|
- "fix casing for all variables"
|
|
- "where is `Foo` defined?"
|
|
- "list the symbols in this Nim file/module"
|
|
- "check this file/module for errors"
|
|
- "show diagnostics for `foo.nim`"
|
|
- "check this project/workspace/repository/package for errors"
|
|
- "fix issues in this project"
|
|
- "fix the repo"
|
|
- "find Nim diagnostics in the current codebase"
|
|
- "show warnings and hints for this repo"
|
|
- "scan the current module tree for Nim issues"
|
|
- "what is the type of this symbol?"
|
|
- "what module/package does this type come from?"
|
|
- "what fields does this type have?"
|
|
- "is this a type alias or a concrete type?"
|
|
- "where is this type defined?"
|
|
|
|
Treat user wording such as **project**, **workspace**, **repository**, **repo**, **package**, **codebase**, **checkout**, and **module tree** as referring to the current Nim project context when they are asking for project-wide diagnostics.
|
|
|
|
Treat user wording such as **file**, **module** (when a concrete Nim file is identified), **source file**, and explicit `*.nim` paths as referring to single-file diagnostics when they are asking for diagnostics for one file.
|
|
|
|
Do **not** pair `nimFindSymbols`, `nimCheckFile`, or `nimCheckProject` with `grep`, `ripgrep`, or shell search "just to double-check". If the task is about a Nim symbol or Nim diagnostics, MCP tools own the search unless they have already failed.
|
|
|
|
## User Terminology vs MCP `kind`
|
|
|
|
Users may ask for symbol categories using looser or non-strict terminology. AI agents MUST map that wording to the exact Nim MCP `kind` values before filtering results from `nimListSymbols(...)` or `nimFindSymbols(...)`.
|
|
|
|
The MCP server returns Nim-oriented kind names derived from nimsuggest symbol kinds with the leading `sk` removed, such as `Const`, `EnumField`, `Field`, `Iterator`, `Converter`, `Let`, `Macro`, `Method`, `Proc`, `Template`, `Type`, `Var`, and `Func`.
|
|
|
|
Use these terminology mappings when interpreting user requests:
|
|
|
|
- **function** / **functions**: usually match `Func` and `Proc`
|
|
- **pure function** / **pure functions**: match `Func`
|
|
- **callable** / **routine**: may include `Func`, `Proc`, `Method`, `Iterator`, `Converter`, `Macro`, and `Template`
|
|
- **class** / **classes**: match `Type`
|
|
- **variable** / **variables**: match `Var` and `Let`
|
|
- **property** / **properties**: match `Field`
|
|
- **enum member** / **enum members**: match `EnumField`
|
|
- **constant** / **constants**: match `Const`
|
|
|
|
## When to Use
|
|
|
|
- **Finding References**: To rename a symbol, update a signature, or find usages.
|
|
- **Symbol Discovery**: To find where a symbol is defined by name.
|
|
- **Type Resolution**: To determine where a local symbol comes from (which module), what its type is, and what fields it has (including private ones).
|
|
- **Naming Standardization**: To fix casing or follow style guides across the project.
|
|
- **Fixing Project Issues**: To iteratively find and resolve all diagnostics in the project.
|
|
- **File Analysis**: To get an overview of all symbols in a file.
|
|
- **File Diagnostics**: To check one specific Nim file for errors, warnings, and hints.
|
|
- **Project Diagnostics**: To check the current Nim project for errors, warnings, and hints.
|
|
- **Debugging Type Mismatches**: When a diagnostic reveals a type mismatch, use `nimFindTypeDefinition` on both sides.
|
|
- **Code Generation / Refactoring**: Before generating code that interacts with a type, find its definition.
|
|
|
|
## Workflows
|
|
|
|
### 1. Find All References or Usages of a Symbol Name
|
|
|
|
Do NOT grep for the name.
|
|
|
|
1. Call `nimFindSymbols(query: "SymbolName")` to get exact `path`, `line`, and `column`.
|
|
2. For each relevant result, call `nimFindReferences(path, line, column)`.
|
|
3. Aggregate the results.
|
|
|
|
### 2. List All Symbols in a File
|
|
|
|
Do NOT read the whole file to find definitions.
|
|
|
|
1. Call `nimListSymbols(path: "path/to/file.nim")`.
|
|
2. If the user asked for a symbol category, filter by the MCP `kind` values.
|
|
3. Use the returned list to navigate or analyze the file structure.
|
|
|
|
### 3. Find Definitions
|
|
|
|
1. Call `nimFindSymbols(query: "query")`.
|
|
|
|
### 4. Resolve Type / Determine Origin of a Symbol
|
|
|
|
1. Call `nimFindTypeDefinition(path, line, column)` with the cursor positioned on the symbol of interest.
|
|
2. The result contains the definition `path`, `line`, `column`, `name`, `type`, and `kind`.
|
|
3. If the user needs to see the full definition, read the source at the returned path/line.
|
|
|
|
### 5. Debug Type Mismatch (Check + Type Definition)
|
|
|
|
1. Call `nimCheckFile(path)` to get the diagnostic with the exact error location.
|
|
2. For the reported location, call `nimFindTypeDefinition(path, line, column)` on the involved symbols.
|
|
3. Resolve the mismatch with the correct type or conversion.
|
|
|
|
### 6. Explore Object Structure (List Symbols + Type Definition)
|
|
|
|
1. Call `nimFindSymbols(query: "TypeName")` to locate the type definition.
|
|
2. Call `nimFindTypeDefinition(path, line, column)` on the type name to confirm the definition location.
|
|
3. Read the source at the definition location to enumerate all fields.
|
|
|
|
### 7. Check a Single Nim File for Diagnostics
|
|
|
|
1. Call `nimCheckFile(path: "path/to/file.nim")`.
|
|
2. Treat the result as the answer unless the user explicitly asked for broader validation.
|
|
3. Use the returned diagnostics to report errors, warnings, and hints for that file.
|
|
|
|
### 8. Check the Current Nim Project for Diagnostics
|
|
|
|
1. Call `nimCheckProject()`.
|
|
2. Use the returned diagnostics to report errors, warnings, and hints for the current Nim project context.
|
|
|
|
### 9. Standardize Naming
|
|
|
|
1. Iterate through the project files one by one.
|
|
2. For each file, call `nimListSymbols(path: "path/to/file.nim")`.
|
|
3. For each symbol found, call `nimFindReferences(path, line, column)`.
|
|
4. Standardize the definition and all identified reference sites to `camelCase`.
|
|
5. After a file has been processed, call `nimCheckFile(path: "path/to/file.nim")` to verify.
|
|
|
|
### 10. Fix Project Issues
|
|
|
|
1. Call `nimCheckProject()` to find all diagnostics in the project.
|
|
2. Analyze the diagnostics and resolve the identified issues.
|
|
3. Repeat steps 1 and 2 until `nimCheckProject()` returns no more issues.
|
|
4. **Limit**: If issues remain after 3 iterations, stop and prompt the user.
|
|
5. **Post-Fix Step**: Ask the user if they would like to check for naming consistency.
|
|
|
|
## Fallback Policy
|
|
|
|
1. **On Error**: If an MCP tool fails due to a technical error, fall back to `grep_search` or other general-purpose tools. State clearly that the MCP tool failed.
|
|
2. **On Empty Results**: If an MCP tool returns no results, do NOT automatically fall back to grep. Prompt the user first.
|
|
3. **Availability**: If MCP tools are unavailable, use general-purpose tools but inform the user.
|
|
|
|
## Critical Constraints
|
|
|
|
- **NO GREP BY DEFAULT**: Never use `grep`, `ripgrep`, or `grep_search` to find Nim symbols or references unless the MCP tools have explicitly errored out.
|
|
- **PROMPT ON EMPTY**: If MCP tools return nothing, ask the user before falling back to grep.
|
|
- **NO MANUAL PARSING**: Do not read large Nim files just to extract symbol locations; use `nimListSymbols` instead.
|
|
- **NO DIY FILE CHECKS**: Do not substitute manual inspection when `nimCheckFile` can return structured diagnostics.
|
|
- **NO DIY PROJECT CHECKS**: Do not substitute shelling out to ad-hoc Nim commands when `nimCheckProject` can return structured project diagnostics.
|
|
- **TOKEN CONSERVATION**: Minimize turns and context by using the most precise tool available.
|
|
|
|
## Anti-Patterns
|
|
|
|
- Calling `nimFindSymbols("Foo")` and then running `rg "Foo"` anyway.
|
|
- Using `rg` for "find all usages" when `nimFindReferences` is available.
|
|
- Reading multiple Nim files to manually enumerate definitions that `nimListSymbols` can return directly.
|
|
- Reading a Nim file to manually search for a type definition when `nimFindTypeDefinition` can resolve it precisely.
|
|
- Grepping for `type Foo* =` instead of using `nimFindTypeDefinition` or `nimFindSymbols`.
|
|
- Running `nimCheckProject()` when the user asked to check one specific Nim file.
|
|
- Manually reading or building a single Nim file first when `nimCheckFile` can return structured diagnostics.
|
|
- Running a manual project build or grep-based log scan first when `nimCheckProject` is available.
|