LSP Server

The reqstool LSP server implements the Language Server Protocol for requirements, SVCs, and annotations across Python, Java, TypeScript, and JavaScript projects. Any LSP-compatible client can use it — IDEs, AI coding assistants (such as Claude Code or GitHub Copilot), and other tooling.

Starting the Server

Installation

The LSP server is included in the reqstool package:

pip install reqstool

stdio mode (recommended)

reqstool lsp

Most LSP clients launch the server automatically via stdio when the language-client configuration is set up.

TCP mode (for debugging)

reqstool lsp --tcp --host 127.0.0.1 --port 2087

Log file

reqstool lsp --log-file /tmp/reqstool-lsp.log

Capabilities

Lifecycle

Server Initialization

LSP method: initialized

Discovers all reqstool projects under each workspace folder and builds in-memory SQLite databases for each on startup.

Server Shutdown

LSP method: shutdown

Closes all open project databases gracefully.

Document Synchronisation

Document Opened

LSP method: textDocument/didOpen

Publishes diagnostics for the opened document immediately.

Document Changed

LSP method: textDocument/didChange

Re-runs diagnostics on every content change event.

Document Saved

LSP method: textDocument/didSave

On save of a reqstool YAML file (requirements.yml, svcs.yml, etc.), rebuilds the affected project database and republishes all diagnostics. For source files, re-runs diagnostics for that file only.

Document Closed

LSP method: textDocument/didClose

Clears diagnostics for the closed document.

Workspace

Workspace Folders Changed

LSP method: workspace/didChangeWorkspaceFolders

Adds or removes project databases when workspace folders are added or removed in the client.

Watched Files Changed

LSP method: workspace/didChangeWatchedFiles

Triggers a full project rebuild when any reqstool YAML file is created, modified, or deleted on disk outside the client.

Intelligence

Hover

LSP method: textDocument/hover

In source files: Markdown tooltip for @Requirements/@SVCs IDs — title, description, lifecycle, SVCs, implementation count, and an "Open Details" link. In reqstool YAML files: JSON Schema description for the hovered field.

Completion

LSP method: textDocument/completion

In source files: autocompletes requirement and SVC IDs inside @Requirements() and @SVCs() annotations. Trigger characters: ", space, :. In YAML files: completes enum values from the JSON Schema.

Go to Definition

LSP method: textDocument/definition

From a source annotation: jumps to the id: line in the YAML file. From svcs.yml (on a requirement reference): jumps to the defining entry in requirements.yml. From mvrs.yml (on an SVC reference): jumps to the defining entry in svcs.yml.

Document Symbols

LSP method: textDocument/documentSymbol

Outline view for reqstool YAML files. Requirements show linked SVCs as children; SVCs show requirements and MVRs as children.

Code Lens

LSP method: textDocument/codeLens

Inline summary above @Requirements/@SVCs annotations: SVC count and pass/fail verification results. Clicking opens the Details panel.

Inlay Hints

LSP method: textDocument/inlayHint

Appends the human-readable title of each requirement or SVC immediately after its ID in source annotations.

Find References

LSP method: textDocument/references

Finds all usages of a requirement or SVC ID across open source files and all reqstool YAML files in the project.

Workspace Symbols

LSP method: workspace/symbol

Global search across all loaded projects for requirements and SVCs matching the query string (by ID or title).

Semantic Tokens

LSP method: textDocument/semanticTokens/full

Colorizes requirement and SVC IDs in source annotations by lifecycle state. Four custom token types: reqstoolDraft, reqstoolValid, reqstoolDeprecated, reqstoolObsolete.

Code Actions

LSP method: textDocument/codeAction

QuickFix actions for unknown-ID and deprecated/obsolete diagnostics. Source action on any known annotation to open the Details panel.

Code action kinds: quickfix, source.

Custom Protocol

The methods in this section are not part of the standard LSP specification. They are reqstool extensions understood only by reqstool-aware clients. Generic LSP clients will ignore them.

reqstool/list

LSP method: reqstool/list

Returns lightweight lists of all requirements, SVCs, and MVRs in the first ready project. Accepts an optional urn to scope the result to a single project node.

Params: { "urn": "<urn>" } (optional)

Returns:

{
  "requirements": [{ "id": "REQ_001", "title": "...", "lifecycle_state": "effective" }],
  "svcs":         [{ "id": "SVC_001", "title": "...", "lifecycle_state": "effective", "verification": "automated-test" }],
  "mvrs":         [{ "id": "MVR_001", "passed": true }]
}

reqstool/list-urns

LSP method: reqstool/list-urns

Returns all URNs in the loaded project graph with their metadata and resolved file paths.

Params: none

Returns: array of:

{
  "urn": "my-service",
  "variant": "microservice",
  "title": "My Service",
  "url": "https://github.com/example/my-service",
  "location": { "type": "local", "uri": "/path/to/reqstool" },
  "file_paths": {
    "requirements": "/path/to/requirements.yml",
    "svcs": "/path/to/software_verification_cases.yml"
  }
}

reqstool/details

LSP method: reqstool/details

Fetches structured data for a single requirement, SVC, MVR, or URN. Can drive a Details panel in an IDE. Searches all ready projects.

The full protocol spec (OpenRPC) is at docs/modules/ROOT/lsp/reqstool-lsp.openrpc.json.

Params: { "type": "<type>", "id": "<id>" }

type id example Description

`type`	`id` example	Description
`requirement`	`REQ_001`	Full requirement with linked SVCs, implementations, lifecycle, and test summary
`svc`	`SVC_001`	Full SVC with linked requirements, test annotations, test results, and MVRs
`mvr`	`MVR_001`	Manual verification result with linked SVC IDs
`urn`	`my-service`	URN metadata, file paths, and entity counts

requirement

REQ_001

Full requirement with linked SVCs, implementations, lifecycle, and test summary

svc

SVC_001

Full SVC with linked requirements, test annotations, test results, and MVRs

mvr

MVR_001

Manual verification result with linked SVC IDs

urn

my-service

URN metadata, file paths, and entity counts

Commands

Refresh Projects

Command ID: reqstool.refresh

Manually rebuilds all project databases and republishes diagnostics. Useful after external changes to YAML files missed by the file watcher.

Run reqstool: Refresh projects from the command palette.

Supported Annotation Languages

The server recognises @Requirements and @SVCs annotations in the following languages:

Python

Language IDs: python

@Requirements("REQ_010", "REQ_011")
@SVCs("SVC_010")

Uses the reqstool-python-decorators package. Multi-line annotations are supported.

Java

Language IDs: java

@Requirements("REQ_010", "REQ_011")
@SVCs("SVC_010")

Same decorator syntax as Python. Multi-line annotations are supported.

TypeScript / JavaScript

Language IDs: typescript, javascript, typescriptreact, javascriptreact

/** @Requirements REQ_010, REQ_011 */
/** @SVCs SVC_010 */

JSDoc-style tag inside a block comment. IDs are comma- or space-separated bare values (no quotes).