Skip to main content
Glama
lampa-mcp-server

lampa-mcp-server

lampa-mcp-server

lampa-mcp-server MCP server

lampa-mcp-server MCP server TDQS

CI Release Release

An MCP server for AI-assisted development on the Lampa open-source TV app.

It gives AI agents (Claude, Cursor, etc.) structured, read-only access to the Lampa source tree — so they understand the repo before making changes.

Runs in two modes:

  • Local stdio — Node process spawned by Cursor / Claude Desktop (unchanged workflow)

  • Cloudflare Workers — remote Streamable HTTP MCP at /mcp with GitHub PAT auth and an R2 source snapshot


What it does

The server exposes 16 tools (plus Worker-only whoami) and curated resources (lampa://plugin-guide, lampa://pitfalls, lampa://events, lampa://landmarks, lampa://edit-rules, lampa://api-surface). Tools are read-only: they never write the Lampa repo.

Tool

Role

summarize_repo

Snapshot metadata, tree, scripts, optional module listing

search_code

Content/regex search

find_files

Paths by name, feature, UI, styles, or specs

read_source

File / core module / template bytes

analyze_plugin

One plugin folder (+ load path if name omitted)

list_catalog

Catalogs (API, events, storage, Maker, …)

trace_symbol

Follow one event, component, file, or deprecated API

explain_docs

Plugin docs, patterns, packaging

plan_change

Plan + targets + impact + risks

draft_patch

Suggested diffs (does not write)

scaffold_plugin

New plugin / setting / hook text (does not write)

validate_code

Plugin score, grep, i18n, build hint

guide_cub

CUB APIs as used in Lampa source

resolve_edit_path

Authoritative src/ / plugins/ path

guide_external_api

Third-party content APIs (TMDB, KinoPoisk, Alloha, MDBList, Jackett, TorrServer, Jellyfin)

guide_plugin_catalog

Real plugin-catalog packaging/publishing pipeline (manifest, obfuscation, routing)

Preferred agent loop:

summarize_repo → explain_docs(mode=plugin_docs) | analyze_plugin
  → search_code | list_catalog | trace_symbol
  → resolve_edit_path → plan_change → scaffold_plugin | draft_patch
  → validate_code

Use resolve_edit_path before editing so you change src/ / plugins/ rather than public/ or build/.

Third-party content-provider APIs (TMDB/KinoPoisk/Alloha/MDBList/Jackett/TorrServer/Jellyfin): guide_external_api. Shipping a plugin into the real lampa-plugins catalog: guide_plugin_catalog. Both are static, curated references — they never expose real credentials and never touch this repo's snapshot.


Related MCP server: codemap

Requirements

  • Node.js 20+

  • For local mode: a checkout of lampa-source

  • For Workers mode: a Cloudflare account, R2 bucket, KV namespace, and a GitHub Personal Access Token (read:user)


Local stdio setup

git clone <this-repo>
cd lampa-mcp-server
npm install
npm run build
export LAMPA_REPO_PATH=/path/to/lampa-source
npm start

Claude Desktop

{
  "mcpServers": {
    "lampa-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/lampa-mcp-server/dist/index.js"],
      "env": {
        "LAMPA_REPO_PATH": "/absolute/path/to/lampa-source"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "lampa-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/lampa-mcp-server/dist/index.js"],
      "env": {
        "LAMPA_REPO_PATH": "/absolute/path/to/lampa-source"
      }
    }
  }
}

Cloudflare Workers (remote MCP)

Architecture: createMcpHandler (MCP SDK v2, stateless) + R2 Lampa snapshot + GitHub PAT auth via resolveExternalToken on @cloudflare/workers-oauth-provider.

1. Create Cloudflare resources

npx wrangler r2 bucket create lampa-mcp-source
npx wrangler kv namespace create OAUTH_KV

Put the returned KV namespace id into wrangler.jsonc (kv_namespaces[0].id).

2. Create a GitHub Personal Access Token

Create a classic or fine-grained PAT with at least read:user.

No GitHub OAuth App / GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET is required.

Optional allowlist (comma-separated GitHub logins) in wrangler.jsonc vars or .dev.vars:

ALLOWED_GITHUB_USERS=your-login,coworker

3. Upload a Lampa source snapshot to R2

# clone Lampa if needed
git clone https://github.com/yumata/lampa-source temp/lampa-source

# local Miniflare R2 (for wrangler dev)
npm run snapshot:upload:local

# production R2
npm run snapshot:upload

Objects land under lampa/manifest.json, lampa/bundle.json (all source text), and lampa/indexes/*.json.

4. Deploy

npm run types:worker
npm run deploy

MCP endpoint: https://lampa-mcp-server.<account>.workers.dev/mcp

5. Connect a remote MCP client

Pass the GitHub PAT as a Bearer token. Cursor example:

{
  "mcpServers": {
    "lampa": {
      "url": "https://lampa-mcp-server.<account>.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer ghp_YOUR_GITHUB_PAT"
      }
    }
  }
}

Or via mcp-remote:

{
  "mcpServers": {
    "lampa": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://lampa-mcp-server.<account>.workers.dev/mcp",
        "--header",
        "Authorization: Bearer ghp_YOUR_GITHUB_PAT"
      ]
    }
  }
}

Prefer storing the PAT in env / secret storage rather than committing it to mcp.json.

Local Worker development

npm run snapshot:upload:local
npm run dev:worker

Then point the MCP inspector / client at http://localhost:8787/mcp with Authorization: Bearer <pat>.


summarize_repo → explain_docs(mode=plugin_docs) | analyze_plugin
    → search_code | list_catalog | trace_symbol
    → resolve_edit_path → plan_change → scaffold_plugin | draft_patch
    → validate_code

Plugin authoring must follow official docs/en (Listener app:ready, SettingsApi, double-load guard). Do not emit $(document).on('appready') or Lampa.Settings.add.

For CUB account/sync work:

guide_cub(topic=auth) → guide_cub(topic=catalog) → guide_cub(topic=sync)
    → guide_cub(topic=models) → guide_cub(topic=endpoint)

Breaking change (v1.x → verb_noun tools)

Aliases, thin wrappers, and v1.7 noun-first names were removed so the catalog stays in the 3–15 range Glama scores. Call the replacement instead:

Removed

Use instead

snapshot_info, list_scripts, list_modules

summarize_repo

read_file, read_file_segment, get_core_module, list_templates, extract_template_html

read_source

find_feature, find_ui_component, find_styles_for_module, list_related_tests

find_files (mode=…)

plan_feature_change, impact_analysis, suggest_edit_targets, risk_scan

plan_change

scaffold_plugin_integration, generate_plugin_boilerplate, add_setting, insert_hook

scaffold_plugin

validate_plugin, run_grep_checks, i18n_check, find_translation_keys, translation_coverage, run_build_hint

validate_code

plugin_docs, doc_lookup, explain_lampa_pattern, platform_packaging_guide

explain_docs

lampa_api_surface, list_all_events, get_storage_schema, get_network_map, find_settings, Maker/socket/flags/…

list_catalog (topic=…)

trace_event, component_lifecycle, module_dependency_map, find_api_calls, upgrade_migration_checker

trace_symbol

cub_api_catalog, cub_endpoint_detail, cub_auth_guide, cub_data_models, cub_sync_guide, cub_timeline_hash_guide

guide_cub

plugin_load_path

analyze_plugin (omit plugin)

repo_overview

summarize_repo

plugin_deep_dive

analyze_plugin

map_lampa

list_catalog

trace_lampa

trace_symbol

explain_lampa

explain_docs

cub_guide

guide_cub


Project structure

src/
├── index.ts                 # Local stdio entry
├── worker.ts                # Cloudflare Worker + PAT auth entry
├── server.ts                # Shared createLampaServer factory
├── config.ts                # Local Config (NodeRepoFs)
├── auth/github-handler.ts   # Public pages + GitHub PAT validation
├── fs/                      # RepoFs: types, Node, R2, paths
├── utils/                   # Async analysis helpers
├── tools/                   # MCP tools
└── resources/               # MCP resources
scripts/
└── upload-snapshot.mjs      # R2 snapshot + index uploader
wrangler.jsonc

Development

npm run build                # wrangler types + tsc → dist/
npm run dev                  # build, then run stdio server
npm start                    # run compiled stdio server
npm run typecheck            # wrangler types + tsc --noEmit
npm run lint
npm run format
npm run types:worker         # regenerate worker-configuration.d.ts (gitignored)
npm run dev:worker           # wrangler dev
npm run deploy               # wrangler deploy
npm run snapshot:upload:local
npm run snapshot:upload

Dependencies (what / why)

Package

Role

@modelcontextprotocol/server

MCP SDK (stdio + shared server factory)

agents

Workers MCP handler (createMcpHandler)

@cloudflare/workers-oauth-provider

Worker auth wrapper (PAT via resolveExternalToken)

hono

Public HTML routes (/, /authorize)

zod

Tool input schemas

typescript

TypeScript 6 compiler + types for typescript-eslint

wrangler

Deploy, wrangler types, local Worker dev

eslint + typescript-eslint + prettier

Lint / format

Runtime deps ship with both the stdio CLI and the Worker. Dev deps are local-only.


License

MIT

Available Tools

16 tools
analyze_pluginAnalyze one Lampa plugin folderA
Read-onlyIdempotent

Single-call report for one plugins/<name> folder: files, Lampa.* usage, Listener follow/send, settings, CSS, and an entry preview truncated to ~30 lines, plus how Lampa loads plugins (src/core/plugins.js). Unlike list_catalog this is scoped to one plugin, unlike trace_symbol it does not follow a single event/file across the repo, unlike validate_code it does not score conventions. Entry file is chosen as main.js, else <plugin>.js, else the first .js file found — plugin itself must be just the case-sensitive directory name (e.g. online, iptv, never a plugins/ prefix or nested path), not a manifest id; omit it for load-path-only output; an unknown folder errors and lists available folders instead of guessing.

Inputs: plugin. Returns: markdown

draft_patchDraft a Lampa unified diffA
Read-onlyIdempotent

Returns TODO unified diffs as text only — does not write the repository. Best with plan_context pasted from plan_change; unlike plan_change, this invents concrete diff hunks; unlike scaffold_plugin, it patches existing files rather than emitting new-plugin boilerplate. target_files, when given, fully overrides inference (the two are never combined) and is capped at the first 5 entries for diff generation even if more are passed (the 'Target files' summary section still lists up to 6); without it, up to 5 files are inferred from request alone, which is weaker than passing plan_context's target list explicitly. Missing files get a 'File not found' note instead of aborting the whole call; the @@ hunks are suggested, not guaranteed to apply — always re-check against read_source before applying by hand.

Inputs: request (required), plan_context, target_files. Returns: markdown

explain_docsExplain Lampa docs, patterns, or packagingA
Read-onlyIdempotent

Read written Lampa guides: official plugin chapters (mode=plugin_docs), a core development pattern with live snippets (mode=pattern), or gulp/npm packaging targets (mode=packaging). Not a live API catalog (list_catalog) and not grep (search_code). Example: chapter=pitfalls vs query='SettingsApi' when chapter is omitted; omit both for the TOC; lang is en (default) or ru; pattern requires the pattern enum; unknown chapter → error listing known ids. Snapshot-only; packaging reads gulpfile.js / package scripts — it does not execute gulp or npm.

Inputs: mode (required), lang, query, chapter, +1 more. Returns: markdown

find_filesFind Lampa files by name or featureA
Read-onlyIdempotent

Locate repo-relative paths by filename, Lampa feature, UI component, stylesheet, or spec — a path finder, not content grep. Unlike search_code, this matches names/paths (except mode=ui/styles, which also attach up to 20/15 content hits); unlike read_source, it does not return file bytes. Example: mode=feature query='player' uses the built-in feature map; mode=name query='full' ext='.js' filters by extension. ext is honored only when mode=name; passing it with mode=feature/ui/styles/tests is silently ignored rather than erroring, so those modes always return every matching extension. Empty matches → list, not an error.

Inputs: query (required), ext, mode. Returns: markdown

guide_cubGuide to CUB cloud APIs in LampaA
Read-onlyIdempotent

Document how Lampa talks to CUB from source — this makes no network calls of its own (pure snapshot read, no auth needed to call this tool), and is not a substitute for cub.rip/developer. Returns markdown text (see output schema), never raw JSON. Unlike list_catalog topic=mirrors/socket, this is CUB-specific. topic=catalog lists REST paths (category/search filter the catalog only, no effect on other topics); endpoint requires path (e.g. bookmarks/dump) and ignores category/search; auth reads auth_focus only (device/add, headers, Permit, Premium, mirrors); models reads model only (bookmark/timeline/favorite shapes); sync takes no parameters and maps dump/changelog/WebSocket; timeline_hash reads example only and explains Utils.hash. Passing any parameter that does not apply to the chosen topic is silently ignored, never an error.

Inputs: topic (required), path, model, search, +3 more. Returns: markdown

guide_external_apiGuide to third-party content-provider APIs used by Lampa pluginsA
Read-onlyIdempotent

Document the real-world content/ratings/torrent-indexer/media-server APIs that Lampa plugins call — TMDB, KinoPoisk (PoiskKino + Unofficial), Alloha, MDBList, Jackett/Prowlarr/JacRed, TorrServer, Jellyfin, TheIntroDB, and the CORS-proxy pattern that fronts them. This is curated from the separate lampa-plugins repository, not the Lampa app source — unlike guide_cub (Lampa→CUB backend only) and unlike list_catalog (Lampa's own API/event/storage surface).\nNever returns secret values (API keys, tokens, passwords) — only provider identity, auth mechanism, and the Lampa.Storage key names a plugin reads credentials from.\ntopic=providers lists all providers (search filters by id/name/category/description); provider_detail requires provider; proxy_pattern takes no parameters and explains the shared Worker-proxy design once for all providers.

Inputs: topic (required), search, provider. Returns: markdown

guide_plugin_catalogGuide to publishing plugins into the real Lampa plugin catalogA
Read-onlyIdempotent

Document how the separate lampa-plugins repository turns plugin source files into the live catalog agents install into Lampa: the extension.json/plugin-manifest.json schema, the obfuscation presets, Cloudflare Pages Functions routing, and a step-by-step publishing checklist. Curated from that repo's scripts/ and functions/, not from the Lampa app source — unlike validate_code (lints one plugin's code against Lampa conventions) and scaffold_plugin (emits new-plugin boilerplate text), this tool covers packaging and distribution once the plugin already works.\nEach topic takes no other parameters and returns a fixed reference document — it does not read this repo's snapshot and never writes files.

Inputs: topic (required). Returns: markdown

list_catalogCatalog Lampa APIs and indexesA
Read-onlyIdempotent

Dump one static catalog from the Lampa snapshot per call. Returns markdown text, not JSON, with no performance cost beyond one tree walk. Not a query (search_code), not a single-symbol walk (trace_symbol), not written docs (explain_docs), and not a live CUB client (guide_cub). scope applies only to api_surface/events/storage (default all); detail=true only affects events; query is a plain substring filter (module name, event name, storage key, component name, flag keyword, or network folder) within the chosen topic — never a repo-wide search. Example: topic=events query='player' detail=true. Empty catalog → markdown, not an error; on R2, full-tree events/storage need a prebuilt index — pass query or a narrower topic (e.g. maker, socket, flags, content_rows, favorites, mirrors) if the index is missing.

Inputs: topic (required), query, scope, detail. Returns: markdown

plan_changePlan a Lampa feature changeA
Read-onlyIdempotent

Generate a step-by-step implementation plan with inferred targets, a reverse-ref sample, and coupling risks for a Lampa change. Call this before draft_patch; unlike draft_patch it does not invent diffs, unlike trace_symbol it covers a whole request rather than one file/event, unlike scaffold_plugin it plans edits to existing code. request='add a sleep timer' + scope_hint='player' concatenates into feature inference; empty inference still returns a plan (not an error). Snapshot-only — does not execute or write; heuristic — not a guarantee; affected-surface list caps at ~12 files.

Inputs: request (required), scope_hint. Returns: markdown

read_sourceRead Lampa source file bytesA
Read-onlyIdempotent

Read bytes from one known path: a repo file, a src/core module, or a src/templates template. Unlike search_code/find_files, this returns contents of a single target — do not dump catalogs (list_catalog). Full files truncate at max_lines (default 300); pass start_line+end_line (1-based, inclusive) for a range (ignores max_lines); kind=file requires file; omit file with kind=core/template to list; missing path → error.

Inputs: file, kind, end_line, max_lines, +2 more. Returns: markdown

resolve_edit_pathResolve authoritative Lampa edit pathA
Read-onlyIdempotent

Map a change kind (lang, sass, template, component, plugin, core, interaction, settings) to the authoritative src/ or plugins/ path and list generated public/build copies to avoid. Call this before plan_change or draft_patch; unlike find_files, this is a fixed landmark table look-up (no filesystem walk, no content search), not a search. Example: kind=plugin name='tracks' returns plugins/tracks specifically, vs kind=lang name='en' returns src/lang/en.js; an unrecognized name does not fail — it falls back to the kind's default authoritative/avoid paths so the call always returns something actionable. name has no effect for kind=sass or kind=settings — those paths are fixed and have no per-name variant, so it is silently ignored there.

Inputs: kind (required), name. Returns: markdown

scaffold_pluginGenerate Lampa plugin, setting, or hook textA
Read-onlyIdempotent

Returns markdown only; does not write the repository — not a patch against existing files (draft_patch). kind=plugin emits a full main.js scaffold: requires plugin_name + description; plugin_kind (screen default | player | context-menu | settings-only) applies only here. kind=setting emits a SettingsApi registration snippet: requires key + label + type (type=toggle aliases trigger). kind=hook emits the best-matching Listener/Player hook: requires trigger. A missing required combo for the chosen kind errors instead of returning a partial scaffold. Follow up with validate_code mode=plugin on the result.

Inputs: kind (required), key, type, label, +7 more. Returns: markdown

search_codeSearch Lampa source contentsA
Read-onlyIdempotent

Search Lampa source contents for a literal or regex and return path:line plus a preview. Use this when you know a symbol or pattern; do not use it to list files by name (find_files), dump catalogs (list_catalog), or read one known path (read_source). Defaults: literal, case-sensitive match (regex=true compiles RegExp exactly as written — no implicit i); extensions .js/.ts/.css/.scss/.html/.json unless globs is set — an empty globs array is treated the same as omitting it, not as 'no extensions'. prefix narrows which folder is walked and globs still filters extensions within it — the two combine rather than override each other. Limits: 100 hits total, 5 per file, 200-char preview per line (fixed, to keep results small enough for one call); invalid regex → error naming the bad pattern; no matches → empty markdown, not an error.

Inputs: query (required), globs, regex, prefix. Returns: markdown

summarize_repoSummarize Lampa repo layoutA
Read-onlyIdempotent

Summarize the Lampa snapshot — commit metadata, top-level folders, plugins, entrypoints, and npm scripts — for first-session orientation. Returns a single markdown report (see output schema), not JSON. Do not use it to read bytes (read_source), search contents (search_code), or list files by name (find_files). Omit subfolder for the compact overview; subfolder='src/components' adds a recursive JS/TS-only listing under that prefix, matched case-sensitively against the snapshot's real path casing (an empty result is a valid 'no JS/TS files here' answer, not an error) on top of the same overview; unknown folder or missing repo → error; stdio needs LAMPA_REPO_PATH and Worker PAT is transport-only (no extra scopes or rate limits beyond GitHub's).

Inputs: subfolder. Returns: markdown

trace_symbolTrace one Lampa symbol through codeA
Read-onlyIdempotent

Follow one event, component, file, or provider through the snapshot graph — not a full catalog (list_catalog) and not raw grep (search_code). Returns a markdown report (see output schema); large result sets are truncated with an explicit count, never silently paginated. Examples: mode=event target='app'; lifecycle target='src/components/full.js'; deps a file path; upgrade a repo-relative file path (not an API name); omit target only for api_calls (optional target is a provider keyword). Missing target otherwise → error; unknown event → markdown note (not a crash); deps reverse-refs cap at 20.

Inputs: mode (required), target. Returns: markdown

validate_codeValidate Lampa plugin, grep, i18n, or buildA
Read-onlyIdempotent

Run checks and hints, not catalogs (list_catalog) and not edit plans (plan_change); prefer analyze_plugin for a descriptive report and trace_symbol for dependency graphs — this tool only scores/lints/hints, it never describes structure. mode=plugin scores a plugin against official pitfalls (target required); grep scans the snapshot for TODOs/console.log/undefined/lang/hardcoded HTML (not a shell, no code execution); i18n looks up key or, if omitted, coverage vs en.js; build returns the npm/gulp command for a goal as text — it never runs it. Example: mode=grep checks=['todos','console_logs']; mode=i18n key='player_playlist' or omit key for a full coverage table. checks only applies to mode=grep (default: all five checks); show_missing only applies to i18n coverage and is ignored once key is set; goal only applies to mode=build; target is required only for mode=plugin (folder or JS path) — missing plugin → error listing folders, missing target for mode=plugin → error naming the requirement.

Inputs: mode (required), key, goal, checks, +2 more. Returns: markdown

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, and the descriptions aggressively call out non-use cases (e.g. search_code vs find_files vs read_source). However, the numerous documentation/catalog tools — list_catalog, explain_docs, guide_cub, guide_external_api, guide_plugin_catalog — overlap conceptually enough that an agent must read carefully to choose correctly.

    Naming Consistency5/5

    All tool names are snake_case and follow a predictable verb_noun or guide_noun pattern. There is no mixing of camelCase, inconsistent verb styles, or vague standalone names.

    Tool Count3/5

    At 16 tools, the server is just over the typical well-scoped range and feels somewhat heavy. The count is partly justified by broad coverage, but several guide/catalog tools could likely be consolidated without losing capability.

    Completeness4/5

    The surface covers orientation, search, file inspection, plugin scaffolding, analysis, planning, patch drafting, validation, and documentation/guides. It is nearly complete for a read-only Lampa developer assistant, though it intentionally does not apply edits or write files, leaving that as a manual follow-up.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server providing 29 tools across 5 layers for semantic TypeScript/JavaScript code intelligence, enabling AI agents to find references, trace impacts, guard APIs, and explain errors without text-search false positives.
      8 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for local-first code intelligence, providing structural code graph, semantic search, and impact analysis to AI agents.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A production-ready MCP server that enables AI assistants to intelligently understand, analyze, edit, navigate, and review software projects with multi-workspace support, Git integration, and semantic search.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that analyzes codebases to provide dependency graphs, impact analysis, and file insights across 15+ programming languages, enabling AI assistants to understand project structure and navigate code efficiently.
      MIT