lampa-mcp-server
This MCP server provides AI agents with structured, read-only access to the Lampa TV app source code, enabling deep understanding, planning, and code generation for Lampa development.
Repository Exploration
Summarize structure, list modules/files/scripts, search code with regex, read file segments.Feature & Architecture Analysis
Locate feature-specific files, map module dependencies and reverse dependencies, conduct impact and risk scans, deep‑analyze plugins and components, extract the full Lampa API surface, storage schema, network map, and UI templates.Event & Data Flow
Trace events to emitters/listeners, map the event bus, and follow data flows.Settings, API & Style Lookup
Find settings registrations, external API calls, styles per module, translation keys, and coverage gaps; list streaming providers and extract template HTML.Planning & Code Generation
Generate step‑by‑step feature plans, suggest optimal edit targets, draft patches, insert hooks, add setting boilerplate, scaffold entire plugins, and generate ready‑to‑use plugin code.Validation & Quality
Validate plugins against conventions, run code‑quality checks (TODOs, console.logs, missing translations), find related tests, get build hints, and perform documentation lookups.
All tools are read‑only and designed for intelligent code discovery, analysis, and assisted Lampa app development.
Provides reference guidance for integrating Lampa with Jellyfin's content API, helping plugin authors use Jellyfin as a third-party content provider.
Provides reference guidance for integrating Lampa with Kinopoisk's content API, helping plugin authors use Kinopoisk as a third-party content provider.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@lampa-mcp-server List all streaming providers in the codebase"
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.
lampa-mcp-server
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
/mcpwith 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 |
| Snapshot metadata, tree, scripts, optional module listing |
| Content/regex search |
| Paths by name, feature, UI, styles, or specs |
| File / core module / template bytes |
| One plugin folder (+ load path if name omitted) |
| Catalogs (API, events, storage, Maker, …) |
| Follow one event, component, file, or deprecated API |
| Plugin docs, patterns, packaging |
| Plan + targets + impact + risks |
| Suggested diffs (does not write) |
| New plugin / setting / hook text (does not write) |
| Plugin score, grep, i18n, build hint |
| CUB APIs as used in Lampa source |
| Authoritative |
| Third-party content APIs (TMDB, KinoPoisk, Alloha, MDBList, Jackett, TorrServer, Jellyfin) |
| 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_codeUse 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 startClaude 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_KVPut 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,coworker3. 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:uploadObjects land under lampa/manifest.json, lampa/bundle.json (all source text), and lampa/indexes/*.json.
4. Deploy
npm run types:worker
npm run deployMCP 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:workerThen point the MCP inspector / client at http://localhost:8787/mcp with Authorization: Bearer <pat>.
Recommended agent workflow
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_codePlugin 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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.jsoncDevelopment
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:uploadDependencies (what / why)
Package | Role |
| MCP SDK (stdio + shared server factory) |
| Workers MCP handler ( |
| Worker auth wrapper (PAT via |
| Public HTML routes ( |
| Tool input schemas |
| TypeScript 6 compiler + types for |
| Deploy, |
| Lint / format |
Runtime deps ship with both the stdio CLI and the Worker. Dev deps are local-only.
License
MIT
Available Tools
16 toolsanalyze_pluginAnalyze one Lampa plugin folderARead-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 diffARead-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 packagingARead-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 featureARead-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 LampaARead-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 pluginsARead-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 catalogARead-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 indexesARead-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 changeARead-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 bytesARead-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 pathARead-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 textARead-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 contentsARead-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 layoutARead-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 codeARead-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 buildARead-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
Scored across 16 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP 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 npm1MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for local-first code intelligence, providing structural code graph, semantic search, and impact analysis to AI agents.2MIT
- AlicenseNot gradedqualityCmaintenanceA 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.1MIT
- AlicenseNot gradedqualityCmaintenanceMCP 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