4D Documentation Viewer

A VS Code extension and MCP (Model Context Protocol) server for browsing 4D command documentation.

Overview

This project provides two ways to access 4D command documentation:

1. VS Code Extension: Browse documentation directly in VS Code with intelligent command detection
2. MCP Server: Use as a Model Context Protocol server with AI assistants like Claude

Both modes share the same caching system for improved performance.

Features

VS Code Extension Features

• Smart Command Detection: Automatically detects 4D commands from:
  • Selected text
  • Word at cursor position
  • LSP/hover information
  • Strips command numbers (e.g., :C123 format) when getting command name
• Two Display Modes:
  • Open in browser (quick external reference)
  • Open in editor webview (integrated documentation with CSS styling)
• Context Menu Integration: Right-click commands for quick access
• Automatic Caching: Faster subsequent lookups

MCP Server Features

• Fetch 4D Command Documentation: Retrieve HTML documentation for any 4D command
• Smart Caching: Automatically caches documentation in OS-specific cache directories
• Cache Management: Clear the cache when needed to fetch fresh documentation
• Browser Integration: Open documentation URLs directly in default browser

Installation

As a VS Code Extension

1. Build the extension:

npm install
npm run build

2. Install locally:
   • Press F5 to run the extension in a new VS Code window (for development)
   • Or package and install:

npm run package
code --install-extension mcp-4d-docs-0.1.0.vsix

As an MCP Server

# Clone or navigate to the project
cd mcp-4d-docs

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Usage

Using the VS Code Extension

1. Open a 4D code file (or any file)
2. Select a 4D command name or place cursor on it
3. Use one of these methods:
   • Command Palette (Cmd+Shift+P):
     • 4D: Open Command Documentation in Browser
     • 4D: Open Command Documentation in Editor
   • Right-click Context Menu:
     • Select command text, right-click, choose option
   • Keyboard Shortcut: (can be configured in VS Code)

If no command is detected, you'll be prompted to enter one manually.

Using as MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "4d-docs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-4d-docs/build/index.js"]
    }
  }
}

For VS Code, add to .vscode/mcp.json:

{
  "mcpServers": {
    "4d-docs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-4d-docs/build/index.js"]
    }
  }
}

Available MCP Tools

get_4d_command_docs

Fetches documentation for a 4D command.

Parameters:

• command_name (string): The name of the 4D command (e.g., "ACTIVITY SNAPSHOT", "ARRAY TO LIST")

Returns:

• HTML documentation content extracted from the <article> tag within the <main> section

Example:

// Fetches from https://developer.4d.com/docs/commands/activity-snapshot
get_4d_command_docs("ACTIVITY SNAPSHOT")

clear_4d_docs_cache

Clears all cached documentation files.

Returns:

• A message indicating the number of files cleared

open_4d_command_in_browser

Opens a 4D command documentation page in the default web browser.

Parameters:

• command_name (string): The name of the 4D command (e.g., "ACTIVITY SNAPSHOT", "ARRAY TO LIST")

Returns:

• A message confirming the URL was opened

Example:

// Opens https://developer.4d.com/docs/commands/activity-snapshot in your browser
open_4d_command_in_browser("ACTIVITY SNAPSHOT")

How It Works

1. Command Detection (VS Code Extension):

   • Checks for selected text first
   • Falls back to word at cursor position
   • Uses LSP hover information when available
   • Prompts for manual entry if needed

2. URL Encoding: Command names are converted to lowercase and spaces are replaced with hyphens

   • Example: "ACTIVITY SNAPSHOT" → "activity-snapshot"

3. Documentation Fetching: The server requests documentation from:

   • https://developer.4d.com/docs/commands/<encoded-command-name>

4. HTML Extraction: The server parses the HTML and extracts the <article> node from within the <main> tag

5. Link Rewriting: Relative /docs/ links are converted to absolute URLs

6. Caching: Results are cached in the OS system cache directory:

   • macOS: ~/Library/Caches/mcp-4d-docs/
   • Windows: %LOCALAPPDATA%\mcp-4d-docs\
   • Linux: ~/.cache/mcp-4d-docs/

7. Cache Key: Each command is cached using an MD5 hash of its name as the filename

8. Display (VS Code Extension):

   • Browser mode: Opens URL directly
   • Webview mode: Displays cached HTML with 4D CSS styling and VS Code theme integration

Development

Project Structure

mcp-4d-docs/
├── src/
│   ├── index.ts              # MCP server implementation
│   ├── extension.ts          # VS Code extension entry point
│   ├── docService.ts         # Shared documentation service
│   ├── commandDetector.ts    # Command name detection logic
│   └── webviewProvider.ts    # Webview panel management
├── build/                    # Compiled JavaScript output
├── logo.png                  # Extension icon
├── package.json             # Project metadata & VS Code extension config
├── tsconfig.json            # TypeScript configuration
├── .vscodeignore            # Files excluded from extension package
└── README.md

Building

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run watch

# Package extension
npm run package

Testing the Extension

Press F5 in VS Code to launch the Extension Development Host with the extension loaded.

Testing the MCP Server

# Use MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

Dependencies

• @modelcontextprotocol/sdk - Model Context Protocol SDK
• cheerio - HTML parsing
• @types/vscode - VS Code API types
• @vscode/vsce - VS Code extension packaging

Configuration

Extension Settings

The extension works out of the box with no configuration needed. It will:

• Activate when opening 4D files (onLanguage:4d)
• Be available via command palette for any file type
• Cache documentation in your system cache directory

Custom Keybindings

You can add custom keyboard shortcuts in VS Code:

{
  "key": "cmd+k cmd+d",
  "command": "4d-docs.openInWebview",
  "when": "editorTextFocus"
},
{
  "key": "cmd+k cmd+b",
  "command": "4d-docs.openInBrowser",
  "when": "editorTextFocus"
}

Publishing

For Personal Use

The extension is ready to use locally. After building and packaging:

npm run package
code --install-extension mcp-4d-docs-0.1.0.vsix

For Distribution

Before publishing to the VS Code Marketplace:

1. Update publisher name in package.json:

   "publisher": "your-actual-publisher-id"
   

2. Add repository URL in package.json:

   "repository": {
     "type": "git",
     "url": "https://github.com/yourusername/mcp-4d-docs.git"
   }
   

3. Add a LICENSE file (e.g., LICENSE.txt with MIT license text)

4. Publish to marketplace:

   vsce publish
   

   Or create a VSIX for sharing:

   npm run package
   # Share the .vsix file
   

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

• [ ] If the remote CSS doesn’t exist (for instance, if it was renamed), consider embedding one in the plugin.
• [ ] Support 4D language highlighting (Prism?).
• [ ] Keep a key pressed when requesting documentation via the command palette to allow forcing a download (i.e., bypassing the cache).