Nuanced LSP Symbols API Reference

Nuanced LSP provides symbol-level APIs for exploring your codebase. These commands let you list definitions, locate identifiers, and find references or symbol relationships within the workspace.

Command	Description
Definitions in File	List all symbol definitions in a specific file.
Find Definition	Find the definition of the identifier at a given position.
Find Identifier	Find identifiers by name within a file.
Find Referenced Symbols	Find symbols referenced by the identifier at a given position.
Find References	Find all references to the identifier at a given position.

These commands use 0-indexed positions in the format line:char (e.g. 0:0 for the first character of the first line).

Definitions in File

List all symbol definitions within a single file.

The file path argument should always be relative to the workspace root.

CLI
TypeScript

> nuanced-lsp definitions-in-file path/to/file

Arguments

Argument	Description	Required
`file`	Path relative to workspace root	✅

CLI options

Option	Description	Default
`--lsp-url <url>`	Nuanced LSP base URL	`"http://127.0.0.1"`
`--lsp-port <n>`	Port for Nuanced LSP	`4444`
`--timeout <s>`	Timeout seconds (`<=0` to skip)	`120`
`--json`	Output machine readable JSON	Text output

Result

Returns JSON array of definitions:

[
  {
    "name": "registerTools",
    "kind": "function",
    "identifier_position": {
      "path": "src/tools/index.ts",
      "position": { "line": 4, "character": 16 }
    },
    "file_range": {
      "path": "src/tools/index.ts",
      "range": {
        "start": { "line": 4, "character": 0 },
        "end": { "line": 7, "character": 1 }
      }
    }
  }
]

Find Definition

Find the definition of the identifier at a given position.

Positions are always 0-indexed in the format line:char (e.g., 0:0 for the first character of the first line).

CLI
TypeScript

> nuanced-lsp find-definition path/to/file 4:16

Arguments

Argument	Description	Required
`file`	Path relative to workspace root	✅
`position`	Position in `line:char` format (0-indexed)	✅

CLI options

Option	Description	Default
`--lsp-url <url>`	Nuanced LSP base URL	`"http://127.0.0.1"`
`--lsp-port <n>`	Port for Nuanced LSP	`4444`
`--timeout <s>`	Timeout seconds (`<=0` to skip)	`120`
`--json`	Output machine readable JSON	Text output

Result

Returns JSON matching FindDefinitionResult:

{
  "raw_response": [
    {
      "range": {
        "end": { "character": 29, "line": 4 },
        "start": { "character": 16, "line": 4 }
      },
      "uri": "file:///workspace/src/tools/index.ts"
    }
  ],
  "definitions": [
    {
      "path": "src/tools/index.ts",
      "position": { "line": 4, "character": 16 }
    }
  ],
  "source_code_context": [
    {
      "file_range": {
        "path": "src/tools/index.ts",
        "range": {
          "start": { "line": 4, "character": 7 },
          "end": { "line": 7, "character": 1 }
        }
      },
      "source_code": "function registerTools(server: McpServer) {\n  registerInitTool(server);\n  registerEnrichTool(server);\n}"
    }
  ],
  "selected_identifier": {
    "name": "registerTools",
    "file_range": {
      "path": "src/tools/index.ts",
      "range": {
        "start": { "line": 4, "character": 16 },
        "end": { "line": 4, "character": 29 }
      }
    },
    "kind": null
  }
}

Find Identifier

Find identifiers by name within a file. Optionally provide a seed position.

You can call this endpoint with a position and without a position to affect its behavior:

Without a position returns all matching identifiers in the file.
With a position scopes the identifier returned to the identifier and position provided, or if none are found at the precise position, the 3 closest (by position) identifiers matching the name.

CLI
TypeScript

> nuanced-lsp find-identifier path/to/file registerTools

With a seed position:

> nuanced-lsp find-identifier path/to/file registerTools --position 15:29

Arguments

Argument	Description	Required
`file`	Path relative to workspace root	✅
`name`	Identifier name to search for	✅

CLI options

Option	Description	Default
`--position <line:char>`	Optional seed position (0-indexed `line:char`)	—
`--lsp-url <url>`	Nuanced LSP base URL	`"http://127.0.0.1"`
`--lsp-port <n>`	Port for Nuanced LSP	`4444`
`--timeout <s>`	Timeout seconds (`<=0` to skip)	`120`
`--json`	Output machine readable JSON	Text output

Result

Returns JSON matching FindIdentifierResult:Without position

{
  "identifiers": [
    {
      "name": "registerTools",
      "file_range": {
        "path": "src/tools/index.ts",
        "range": {
          "start": { "line": 4, "character": 16 },
          "end":   { "line": 4, "character": 29 }
        }
      },
      "kind": null
    }
  ]
}

With position

{
  "identifiers": [
    {
      "name": "registerTools",
      "file_range": {
        "path": "src/tools/index.ts",
        "range": {
          "start": { "line": 4, "character": 16 },
          "end":   { "line": 4, "character": 29 }
        }
      },
      "kind": null
    }
  ]
}

Find Referenced Symbols

For a target symbol, returns all symbols referenced within the target’s implementation. The referenced symbols are categorized into the following:

Workspace symbols: symbols found in the workspace along with their definitions.
External symbols: symbols from external libraries or built-in functions.
Not found symbols: symbols Nuanced LSP was unable to resolve.

The full scan option uses more permissive rules for finding referenced symbols. Depending on the LSP server, may use type hints and chained indirection.

CLI
TypeScript

> nuanced-lsp find-referenced-symbols --full-scan path/to/file 4:16

CLI options

Option	Description	Default
`file`	Path relative to workspace root	—
`position`	Position in `line:char` format (0-indexed)	—
`--full-scan`	Perform a broader workspace scan for references	`false`
`--lsp-url <url>`	Nuanced LSP base URL	`"http://127.0.0.1"`
`--lsp-port <n>`	Port for Nuanced LSP	`4444`
`--timeout <s>`	Timeout seconds (`<=0` to skip)	`120`
`--json`	Output machine readable JSON	Text output

Result

Returns JSON matching FindReferencedSymbolsResult (excerpt):

{
  "workspace_symbols": [
    {
      "reference": {
        "name": "registerInitTool",
        "file_range": {
          "path": "src/tools/index.ts",
          "range": {
            "start": { "line": 5, "character": 2 },
            "end":   { "line": 5, "character": 18 }
          }
        },
        "kind": "all-references"
      },
      "definitions": [
        {
          "name": "registerInitTool",
          "kind": "function",
          "identifier_position": {
            "path": "src/tools/init.ts",
            "position": { "line": 12, "character": 16 }
          },
          "file_range": {
            "path": "src/tools/init.ts",
            "range": {
              "start": { "line": 12, "character": 0 },
              "end":   { "line": 22, "character": 1 }
            }
          }
        }
      ]
    }
  ],
  "external_symbols": [],
  "not_found": []
}

Find References

Find all references to the identifier at a given position. Optionally include lines of code context around each reference.

The optional context lines parameter includes lines of source code around each found reference.

CLI
TypeScript

> nuanced-lsp find-references path/to/file 6:21

Include context lines:

> nuanced-lsp find-references --context-lines 3 path/to/file 6:21

Arguments

Argument	Description	Required
`file`	Path relative to workspace root	✅
`position`	Position in `line:char` format (0-indexed)	✅

CLI options

Option	Description	Default
`--context-lines <n>`	Include `n` lines of surrounding code for each reference	`0`
`--lsp-url <url>`	Nuanced LSP base URL	`"http://127.0.0.1"`
`--lsp-port <n>`	Port for Nuanced LSP	`4444`
`--timeout <s>`	Timeout seconds (`<=0` to skip)	`120`
`--json`	Output machine readable JSON	Text output

Result

Returns JSON matching FindReferencesResult (excerpt):

{
  "raw_response": [{ "range": { "start": { "line": 4, "character": 30 }, "end": { "line": 4, "character": 36 } }, "uri": "file:///workspace/src/tools/index.ts" }],
  "references": [
    { "path": "src/tools/index.ts", "position": { "line": 4, "character": 30 } },
    { "path": "src/tools/index.ts", "position": { "line": 5, "character": 19 } },
    { "path": "src/tools/index.ts", "position": { "line": 6, "character": 21 } }
  ],
  "context": [
    {
      "file_range": {
        "path": "src/tools/index.ts",
        "range": { "start": { "line": 4, "character": 0 }, "end": { "line": 4, "character": 0 } }
      },
      "source_code": ""
    }
  ],
  "selected_identifier": {
    "name": "server",
    "file_range": {
      "path": "src/tools/index.ts",
      "range": { "start": { "line": 6, "character": 21 }, "end": { "line": 6, "character": 27 } }
    },
    "kind": null
  }
}

Getting Started

Nuanced MCP Server

Nuanced LSP Container

Definitions in File

Arguments

CLI options

Result

Find Definition

Arguments

CLI options

Result

Find Identifier

Arguments

CLI options

Result

Find Referenced Symbols

CLI options

Result

Find References

Arguments

CLI options

Result

Getting Started

Nuanced MCP Server

Nuanced LSP Container

​Definitions in File

​Arguments

​CLI options

​Result

​Find Definition

​Arguments

​CLI options

​Result

​Find Identifier

​Arguments

​CLI options

​Result

​Find Referenced Symbols

​CLI options

​Result

​Find References

​Arguments

​CLI options

​Result

Definitions in File

Arguments

CLI options

Result

Find Definition

Arguments

CLI options

Result

Find Identifier

Arguments

CLI options

Result

Find Referenced Symbols

CLI options

Result

Find References

Arguments

CLI options

Result