GAP System Support

English | 简体中文

This extension provides intelligent code editing powered by tree-sitter-gap, GAP code running, a help system, language model tools, and MCP support for GAP in VS Code, so that GAP users can write, read, and run GAP code and look up GAP documentation at any time. The file extensions recognized as GAP are .g, .gi, .gd, and .gap.

GAP is a system for computational discrete algebra, with particular emphasis on Computational Group Theory. GAP provides a programming language, a library of thousands of functions implementing algebraic algorithms written in the GAP language as well as large data libraries of algebraic objects. For more information, see the GAP official website.

Features

• Semantic highlighting and syntax diagnostics: based on tree-sitter-gap.
• Code completion: provides completion for GAP constants, keywords, statement structures, and GAP functions (including functions from other GAP files loaded via Read).
• Hover information: hovering over a symbol shows its static category, such as function, variable, parameter, or record field. Built-in functions show their signature, a short documentation summary when the GAP documentation is configured, and a link to GAP Help. Language keywords, operators, and the ; statement terminator show syntax-highlighted snippets with concise descriptions.
• Definition navigation: native Go to Definition and Peek Definition support for statically recognizable user-defined GAP symbols.
• Reference navigation: Command+click on macOS or Ctrl+click on Windows/Linux opens the native Peek view when a definition has references. Native Find All References (Shift+F12) is also supported. The selected occurrence is omitted; definitions without references jump directly to themselves.
• Running GAP code: runs the current GAP file in the VS Code integrated terminal, with configurable GAP command line options.
• Help system: built-in GAP help system with two search modes (switchable at any time in the settings or the Quick Pick search box), with results filterable by book.
  • prefix: same behavior as ?topic in GAP
  • substring: same behavior as ??topic in GAP
• Documentation viewer: search results are displayed in a webview panel.
• Language model tools and MCP: GAP help lookup and syntax checking tools that agents can automatically invoke in chat.

Getting Started

1. Install GAP and Configure the PATH

First, make sure GAP is installed and added to the system PATH. If it is not on the PATH, you can follow the steps below to configure it.

Windows: If GAP was installed via the .exe installer, run the following in PowerShell:

$userPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', $userPath + ';C:\Program Files\GAP-4.16.1\runtime\opt\gap-4.16.1;C:\Program Files\GAP-4.16.1\runtime\bin', 'User')

After running the commands above, open a new PowerShell terminal and run gap --version. If it prints the GAP version, your environment is configured successfully.

Linux / macOS: Run the following in a terminal (on macOS, replace ~/.bashrc with ~/.zshrc):

echo 'export PATH="/opt/gap-4.16.1:$PATH"' >> ~/.bashrc
source ~/.bashrc

Finally, run gap --version to verify that it is configured correctly.

Note: If your installation path differs from the examples, replace it with your actual installation path.

2. Set the GAP Documentation Paths in the Extension Settings

Set the following settings in the walkthroughs on the Welcome page or in the VS Code extension settings:

• gap.docPath: the absolute path of the doc/ folder, for example:
  • Windows: C:\Program Files\GAP-4.16.1\runtime\opt\gap-4.16.1\doc
  • Linux/macOS: /opt/gap-4.16.1/doc
• gap.pkgPath: the absolute path of the pkg/ folder, for example:
  • Windows: C:\Program Files\GAP-4.16.1\runtime\opt\gap-4.16.1\pkg
  • Linux/macOS: /opt/gap-4.16.1/pkg

Language Model Tools and MCP

Both interfaces provide the same five tools and can be enabled or disabled independently.

• Language model tools: available to agents in VS Code, controlled by
  gap.tools.enabled and enabled by default.
• MCP server: available to VS Code and external MCP clients, controlled by
  gap.mcp.enabled and disabled by default.

After enabling MCP in a trusted workspace, run GAP: Copy MCP Connection Configuration to obtain the connection configuration for external clients.

Settings

Commands

Press Ctrl+Shift+P or F1 to open the Command Palette and use the following commands:

The editing, help, and completion data commands are also available in the editor context menu (right-click menu) of GAP files, where GAP: Search GAP Help and GAP: Run GAP File are at the top level, while the remaining commands are grouped in the More GAP Commands submenu. The MCP connection and token reset commands are available from the Command Palette only.

Development

Implementation and coverage notes:

• Definition and reference navigation
• Definition navigation coverage
• Hover information

First, install the dependencies and compile the TypeScript sources:

npm install
npm run compile

Run the tests:

npm test

To build a VSIX for manual testing in an Extension Development Host or a local
VS Code installation:

npx @vscode/vsce package

Then press F5 to start debugging.

Acknowledgements

• Syntax highlighting is implemented based on the tree-sitter-gap query files.
• The extension icon is from gap-logo.
• Thanks to @JieteXue for contributing to this project, and to everyone who has supported its development.

Third Party Notices

• The query files and grammar rules are from tree-sitter-gap (MIT, Copyright (c) 2019 Max Horn, contributor Reinis Cirpons).
• The GAP logo is © Max Horn (contributor Reinis Cirpons) and a trademark of the GAP project, licensed under CC BY-SA 4.0. Derivatives must be shared under the same license. See gap-logo.
• See THIRDPARTYNOTICES.md for third-party notices.

License

MIT