How do I use lsl-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@lsl-mcp check this LSL script for common pitfalls" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

lsl-mcp

A Model Context Protocol (MCP) server providing accurate LSL (Linden Scripting Language) reference data to AI coding assistants. Grounded in the official Second Life wiki, with a curated database of AI-specific pitfalls.

Motivation

AI coding assistants (Claude Code, Kiro, etc.) frequently produce incorrect LSL — hallucinated function names, unsupported syntax, and wrong signatures. This server gives those tools a live, authoritative reference to query against rather than relying on training data.

Design Goals

Portable LSL only — no Firestorm-specific syntax
AI-aware — pitfalls are categorised and tagged by which tool produced them
Git-tracked — JSON is the source of truth; SQLite is always derivable
Incrementally maintainable — new pitfalls are captured via CLI as they are discovered

Project Structure

lsl-mcp/
├── server.py              # MCP server entrypoint
├── db/
│   ├── schema.sql         # Table definitions
│   └── lsl.db             # SQLite database (gitignored)
├── data/
│   ├── functions/         # One JSON file per LSL function (source of truth)
│   ├── pitfalls.json      # Language pitfalls collection (source of truth)
│   └── constants.json     # LSL constants
├── scripts/
│   ├── scrape_wiki.py     # Populates data/functions/ from the LSL wiki
│   ├── load_db.py         # Imports JSON data into lsl.db
│   └── add_pitfall.py     # CLI tool for adding new pitfalls
├── tools/
│   ├── lookup.py          # lsl_lookup_function, lsl_search
│   ├── pitfalls.py        # lsl_get_pitfalls, lsl_check_code
│   └── reference.py       # lsl_list_events, lsl_constants
└── pyproject.toml

Requirements

Python 3.11+
uv (recommended) or pip

Initial Setup

1. Install dependencies

Using uv (recommended):

uv sync

Using pip:

pip install -e .

For development (includes pytest):

uv sync --dev
# or
pip install -e ".[dev]"

2. Scrape the LSL wiki

Populates data/functions/ with one JSON file per function. Approximately 700 functions; takes several minutes due to polite request throttling.

python scripts/scrape_wiki.py

Test a single function first:

python scripts/scrape_wiki.py --function llListen --dry-run

2. Initialise the database

Creates db/lsl.db from db/schema.sql and loads all JSON data.

python scripts/load_db.py

3. Connect to Claude Code

# using uv (recommended)
claude mcp add --transport stdio lsl -- uv run /path/to/lsl-mcp/server.py

# using python directly
claude mcp add --transport stdio lsl -- python /path/to/lsl-mcp/server.py

Or add a .mcp.json to your project root for project-wide sharing:

{
  "mcpServers": {
    "lsl": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "/path/to/lsl-mcp/server.py"]
    }
  }
}

Verify the server is connected:

claude mcp list

MCP Tools

Tool	Description
`lookup_function(name)`	Exact or fuzzy match on function name. Returns full record including signature, parameters, caveats, and known AI pitfalls. Falls back to `did_you_mean` on miss.
`search_functions(query, limit?)`	Full-text search across function names and descriptions. Returns ranked summary list.
`get_pitfalls(category?, ai_source?)`	Returns all pitfall entries, optionally filtered by category or source tool.
`check_code(code)`	Scans raw LSL source for known AI-generated mistakes. Returns line numbers and suggestions.
`list_events(name?)`	Returns all valid LSL event signatures, or looks up one by name.
`get_constants(category?, name?)`	Returns constants by category or direct name lookup.

Recommended AI workflow

Before starting an LSL task:
    get_pitfalls()               ← full briefing on known mistakes

While writing LSL:
    lookup_function("llFoo")     ← verify signature before use
    list_events("touch_start")   ← verify event name and parameters
    get_constants("permissions")  ← browse constants by category

Before presenting code to the user:
    check_code(generated_lsl)    ← catch mistakes before they reach the user

Pitfall Categories

Category	Description
`reserved_words`	LSL type names or keywords used as variable identifiers
`nonexistent_functions`	Hallucinated function names with no LSL equivalent
`unsupported_syntax`	Syntax valid in other languages but a compile error in LSL
`scoping`	Global variable assumptions or state scoping errors
`type_coercion`	Implicit casting that LSL does not perform
`state_behavior`	Unexpected behavior around state changes

Adding a Pitfall

When an AI tool produces incorrect LSL, capture it:

python scripts/add_pitfall.py \
  --category nonexistent_functions \
  --title "llStringReplace does not exist in LSL" \
  --bad "llStringReplace(src, old, new)" \
  --good "llReplaceSubString(src, pattern, replacement, count)" \
  --ai-source kiro \
  --notes "llStringReplace is a plausible-sounding hallucination, likely confused with string replace conventions in other languages."

Then sync the database and commit:

python scripts/load_db.py --only pitfalls
git add data/pitfalls.json
git commit -m "pitfall(func_001): llStringReplace does not exist [kiro]"

Claude-assisted capture

Describe the mistake to Claude in plain language. Claude will format it into the correct schema and emit the exact CLI command to run. You verify, run it, and commit. Claude never writes to the database directly — the CLI is the deterministic protocol.

`--dry-run`

Preview what would be written without touching any files:

python scripts/add_pitfall.py --category unsupported_syntax --title "..." --dry-run

Refreshing Wiki Data

Re-scrape all functions and reload:

python scripts/scrape_wiki.py --overwrite
python scripts/load_db.py --only functions

Re-scrape a single function:

python scripts/scrape_wiki.py --function llReplaceSubString
python scripts/load_db.py --only functions

Database

db/lsl.db is gitignored — it is always fully derivable from the JSON sources via load_db.py. Only data/ and db/schema.sql are version-controlled.

To rebuild from scratch:

python scripts/load_db.py --reset

Pitfall ID Format

IDs are assigned automatically by add_pitfall.py based on category:

Category	Prefix	Example
`reserved_words`	`lang`	`lang_001`
`nonexistent_functions`	`func`	`func_001`
`unsupported_syntax`	`syn`	`syn_001`
`scoping`	`scope`	`scope_001`
`type_coercion`	`type`	`type_001`
`state_behavior`	`state`	`state_001`

Known Pitfalls

ID	Category	Issue	Source
`lang_001`	`reserved_words`	`key` used as variable name	kiro
`func_001`	`nonexistent_functions`	`llStringReplace` does not exist	kiro
`syn_001`	`unsupported_syntax`	Ternary operator not supported	kiro, claude-code
`syn_002`	`unsupported_syntax`	Switch statements not supported	kiro, claude-code

Testing

# Run all tests
python3 -m pytest

# Verbose output
python3 -m pytest -v

# Single module
python3 -m pytest tests/test_pitfalls.py

Tests use an in-memory SQLite fixture database built from db/schema.sql — no real lsl.db or network access required. The conftest.py fixture patches DB_PATH in all tool modules automatically.

Test file	Coverage
`test_lookup.py`	`lsl_lookup_function`, `lsl_search`
`test_pitfalls.py`	`lsl_get_pitfalls`, `lsl_check_code`
`test_reference.py`	`lsl_list_events`, `lsl_constants`
`test_add_pitfall.py`	ID generation logic in `add_pitfall.py`

gitignore

db/lsl.db
data/functions/
data/scrape_errors.json
__pycache__/
*.pyc
.venv/

data/functions/ is gitignored because it is fully regenerable from the wiki. Only data/pitfalls.json and data/constants.json are committed — these contain hand-curated data that cannot be scraped.

lsl-mcp

lsl-mcp

Motivation

Design Goals

Project Structure

Requirements

Initial Setup

1. Install dependencies

2. Scrape the LSL wiki

2. Initialise the database

3. Connect to Claude Code

MCP Tools

Recommended AI workflow

Pitfall Categories

Adding a Pitfall

Claude-assisted capture

`--dry-run`

Refreshing Wiki Data

Database

Pitfall ID Format

Known Pitfalls

Testing

gitignore

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API