Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion docs/assistant.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,12 @@ shared with namespaces (admins can share with everyone), and switched on or off
only when the skill applies.
- **Hook**: runs when a question arrives, before or after a tool, or after an answer, to add context, block a tool or
call one. Your own hooks run in your conversations; other people's run only when an admin shared them.
- **Plugin**: a bundle of tools, skills and hooks, shared and switched off as one.
- **MCP server** (admins add them): a server that speaks the Model Context Protocol over Streamable HTTP, at the
address an admin gives (this machine and the local network included, as for the model's address), with the headers
it needs (a token). Lens lists its tools when it's saved, and the assistant calls them as `<server>__<tool>`: one the
server marks read-only answers at once, the others ask for approval. Servers that run as a program (stdio) aren't
run.
- **Plugin**: a bundle of tools, skills, hooks and MCP servers, shared and switched off as one.

Make one however suits you:

Expand Down Expand Up @@ -172,6 +177,26 @@ when: someone asks for a recap of a meeting
Find the meeting, read it, and answer with three bullets: decisions, owners, dates.
```

### Skills and plugins from marketplaces

Lens reads Anthropic's open plugin and skill formats as they are, so what's made for Claude installs here unchanged:

- **Marketplaces** (`/api/v1/marketplaces`): a repository with `.claude-plugin/marketplace.json`. Admins add them,
which is the approval: Anthropic's own (`anthropics/skills`, `anthropics/claude-plugins-official`) are suggested,
and any other is added by its address (`owner/repo`, a GitHub or GitLab link, or a link to its marketplace.json),
which is how a team runs a custom one. Everyone who can edit browses them, previews a plugin (what it adds and what
Lens leaves out) and installs it.
- **Links and files** (`POST /api/v1/extensions/import`, `/import/archive`): a plugin or a skill from a GitHub or
GitLab repository or folder, or a `.zip`, `.skill` or `.tar.gz`.

An installed plugin is one Lens plugin, yours and private until you share it; installing it again saves its new
version. A skill (a folder with SKILL.md) is a skill, and the assistant reads its text files (references, examples,
scripts) when the instructions point at them; nothing in them runs. A command (`commands/*.md`) is a skill the
assistant follows when someone asks for it, and an agent (`agents/*.md`) is a prompt tool with the agent's instructions
as its system prompt. Claude Code's hooks run commands on the computer, so they're left out. A plugin's MCP servers on
the network (`.mcp.json`) come along when an admin installs it; those that run as a program are left out. Repositories are read from GitHub or GitLab (or the archive link) through the same guard as web
tools: public addresses only.

`ai.extensions: false` turns every extension off.

## Setting up and running the server by chat
Expand Down
3 changes: 3 additions & 0 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ and sees exactly what that person sees: their namespaces, the collections they w
those open. Its tools read, except the few listed under [Tools](#tools) that suggest or write, which need a
write-scope token and editor access.

It works the other way too: Lens's own assistant calls the tools of MCP servers an admin adds, as extensions
([Extending the assistant](assistant.md#extending-the-assistant-tools-skills-hooks-and-plugins)).

## Connecting

The server is at `/mcp` on the web app's address: `https://lens.example.org/mcp` (`http://localhost:3000/mcp`
Expand Down
2 changes: 2 additions & 0 deletions fastapi_backend/app/api/v1/router.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
import_hooks,
imports,
jobs,
marketplaces,
metadata,
namespaces,
notebook,
Expand Down Expand Up @@ -106,6 +107,7 @@
workflows,
custom_nodes,
extensions,
marketplaces,
chats,
collections,
batches,
Expand Down
30 changes: 27 additions & 3 deletions fastapi_backend/app/api/v1/routes/extensions.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,16 @@
from fastapi import APIRouter, HTTPException, Request

from app.api.deps import Acl, Cfg, CurrentUser, Db, Principal, Writer, domain_errors
from app.domain import ai_tools, auth, extensions
from app.domain import ai_tools, auth, extensions, marketplace
from app.schemas.common import Created, Ok
from app.schemas.extensions import (
Extension,
ExtensionCreate,
ExtensionDetail,
ExtensionImportArchive,
ExtensionImported,
ExtensionImportLink,
ExtensionImportPreview,
ExtensionTest,
ExtensionTestResult,
ExtensionUpdate,
Expand Down Expand Up @@ -68,6 +72,27 @@ def create_extension(body: ExtensionCreate, user: Writer, db: Db) -> Created:
return Created(id=eid)


@router.post("/import")
def import_link(body: ExtensionImportLink, user: Writer, db: Db, cfg: Cfg) -> ExtensionImportPreview | ExtensionImported:
"""A plugin or skill in Anthropic's format from a link: a GitHub or GitLab repository or folder, or a .zip. With
`preview`, what it would add and leave out; else installed as your own (importing it again: a new version)."""
with _errors():
out = marketplace.import_link(db, cfg, me(user), body.url, dry=body.preview)
if not body.preview:
auth.audit(db, user.as_audit(), "extension.import", f"extension:{out['id']}", {"url": body.url, "version": out["version"]})
return ExtensionImportPreview(**out) if body.preview else ExtensionImported(**out)


@router.post("/import/archive")
def import_archive(body: ExtensionImportArchive, user: Writer, db: Db) -> ExtensionImportPreview | ExtensionImported:
"""A plugin or skill from a .zip, .skill or .tar.gz you send (as base64)."""
with _errors():
out = marketplace.import_archive(db, me(user), body.filename, body.data, dry=body.preview)
if not body.preview:
auth.audit(db, user.as_audit(), "extension.import", f"extension:{out['id']}", {"file": body.filename, "version": out["version"]})
return ExtensionImportPreview(**out) if body.preview else ExtensionImported(**out)


@router.get("/{eid}")
def get_extension(eid: int, user: CurrentUser, db: Db, version: int | None = None) -> ExtensionDetail:
"""One version (default: the current one), as a manifest too, and the list of versions."""
Expand Down Expand Up @@ -107,9 +132,8 @@ def test_extension(eid: int, body: ExtensionTest, user: Writer, acl: Acl, db: Db
needs `confirm`."""
with _errors():
g = extensions.visible_one(db, me(user), eid)
items = g["spec"]["items"] if g["kind"] == "plugin" else [g]
name = body.tool or (g["name"] if g["kind"] == "tool" else None)
t = next((it for it in items if it.get("kind") == "tool" and it["name"] == name), None)
t = next((it for it in extensions.tool_items(g) if it["name"] == name), None)
if not t:
raise ValueError("name one of its tools to try")
if t["spec"]["effect"] == "change" and not body.confirm:
Expand Down
80 changes: 80 additions & 0 deletions fastapi_backend/app/api/v1/routes/marketplaces.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
"""Marketplaces: where plugins and skills in Anthropic's format are installed from. Admins add them; people who write
extensions install from them."""

from __future__ import annotations

from fastapi import APIRouter

from app.api.deps import AdminWriter, Cfg, CurrentUser, Db, Writer
from app.api.v1.routes.extensions import _errors, me
from app.domain import auth, marketplace
from app.schemas.common import Created, Ok
from app.schemas.extensions import (
ExtensionImported,
ExtensionImportPreview,
Marketplace,
MarketplaceCreate,
MarketplacePlugin,
MarketplaceSuggestion,
)

router = APIRouter(prefix="/marketplaces", tags=["extensions"])


@router.get("")
def list_marketplaces(user: CurrentUser, db: Db) -> list[Marketplace]:
return marketplace.listing(db)


@router.get("/suggested")
def suggested_marketplaces(user: CurrentUser, db: Db) -> list[MarketplaceSuggestion]:
"""Anthropic's marketplaces, when they aren't added yet."""
return marketplace.suggested(db)


@router.post("")
def add_marketplace(body: MarketplaceCreate, user: AdminWriter, db: Db, cfg: Cfg) -> Created:
"""Add a marketplace by its address; its list of plugins is read now."""
with _errors():
mid = marketplace.add(db, cfg, me(user), body.source, body.title)
auth.audit(db, user.as_audit(), "marketplace.add", f"marketplace:{mid}", {"source": body.source})
return Created(id=mid)


@router.post("/{mid}/refresh")
def refresh_marketplace(mid: int, user: AdminWriter, db: Db, cfg: Cfg) -> Ok:
"""Read its list of plugins again."""
with _errors():
marketplace.refresh(db, cfg, me(user), mid)
return Ok()


@router.delete("/{mid}")
def delete_marketplace(mid: int, user: AdminWriter, db: Db) -> Ok:
"""Takes it away; what was installed from it stays."""
with _errors():
marketplace.remove(db, me(user), mid)
auth.audit(db, user.as_audit(), "marketplace.delete", f"marketplace:{mid}")
return Ok()


@router.get("/{mid}/plugins")
def list_marketplace_plugins(mid: int, user: CurrentUser, db: Db) -> list[MarketplacePlugin]:
with _errors():
return marketplace.plugins(db, me(user), mid)


@router.post("/{mid}/plugins/{name}/preview")
def preview_marketplace_plugin(mid: int, name: str, user: Writer, db: Db, cfg: Cfg) -> ExtensionImportPreview:
"""What installing it would add to the assistant, and what Lens leaves out."""
with _errors():
return marketplace.preview(db, cfg, me(user), mid, name)


@router.post("/{mid}/plugins/{name}/install")
def install_marketplace_plugin(mid: int, name: str, user: Writer, db: Db, cfg: Cfg) -> ExtensionImported:
"""Install it as your own plugin, private until you share it; installing it again brings its new version."""
with _errors():
eid, n = marketplace.install(db, cfg, me(user), mid, name)
auth.audit(db, user.as_audit(), "extension.import", f"extension:{eid}", {"marketplace": mid, "plugin": name, "version": n})
return ExtensionImported(id=eid, version=n)
1 change: 1 addition & 0 deletions fastapi_backend/app/domain/activity.py
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@
"spaces": "space",
"collections": "collection",
"extensions": "extension",
"marketplaces": "marketplace",
"sources": "watch_path",
"watches": "watch_path",
"sensors": "sensor",
Expand Down
12 changes: 9 additions & 3 deletions fastapi_backend/app/domain/ai_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -483,13 +483,20 @@ def run(**args):

return run

def t_use_skill(self, name):
def t_use_skill(self, name, file=None):
s = (self.ext.skills if self.ext else {}).get(name)
if not s:
raise ValueError(f"no skill {name}")
files = s["spec"].get("files") or {}
if file:
if file not in files:
raise ValueError(f"the skill {name} has no file {file}; it has: {', '.join(files) or 'none'}")
return {"skill": name, "file": file, "text": files[file]}, f"Read {file} from the skill {name}"
out = {"skill": name, "instructions": s["spec"]["instructions"]}
if s["spec"].get("tools"):
out["tools"] = s["spec"]["tools"]
if files:
out["files"] = list(files)
return out, f"Read the skill {name}"

# ---- extensions, from chat ----
Expand Down Expand Up @@ -1148,8 +1155,7 @@ def run_extension(db, cfg, args, user, admin, readable, toolbox=None):
me = extensions.who(user["id"], user.get("email"), admin, {s: "viewer" for s in readable})
if g.get("deleted_at") or not g.get("enabled") or not extensions.can_use(g, me):
raise ValueError("that extension was switched off or removed")
items = g["spec"]["items"] if g["kind"] == "plugin" else [g]
t = next((it for it in items if it.get("kind") == "tool" and it["name"] == args["tool"]), None)
t = next((it for it in extensions.tool_items(g) if it["name"] == args["tool"]), None)
if not t:
raise ValueError(f"the extension has no tool {args['tool']} any more")
out = extensions.run_tool(db, cfg, t["spec"], extensions.tool_args(t["spec"], args.get("args") or {}), toolbox=toolbox)
Expand Down
Loading
Loading