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

Register the server with Claude Code (personal scope):

# 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.