selvans

selvans is a framework that makes any web application natively operable by AI agents through the Model Context Protocol (MCP).

Instead of using browser automation, AI agents connect directly to your application through a structured protocol — observing the UI semantic tree and calling typed tools to interact with it.

How It Works

 External AI (Claude Desktop, Cursor…)
          │  MCP / SSE
          ▼
  ┌──────────────────┐
  │  selvans-core │  ← Hub service (WebSocket + MCP server + admin UI)
  └──────┬─────┬─────┘
         │ WS  │ WS
    ┌────┘     └────┐
    ▼               ▼
Angular App    Python Backend
(selvans-   (selvans-
  angular)       python)

1. selvans-core is the central hub. It exposes an MCP server (SSE) that external AI clients connect to, and a WebSocket endpoint that your frontend and backend connect to.

2. selvans-angular integrates into your Angular app. It registers a semantic UI tree and built-in tools (click_element, form_input, get_page_state…) with the Core.

3. selvans-python integrates into your Python/FastAPI backend. It registers typed service operations with the Core.

4. The AI calls tools and operations through the Core, which routes them to the right app in real time.

Related MCP server: Playwright MCP

Repository Structure

selvans/
├── packages/
│   ├── selvans-angular/       # Angular library (npm)
│   └── selvans-python/        # Python client library (PyPI)
├── services/
│   └── selvans-core/          # Hub service (Docker)
├── demos/
│   ├── selvans-angular-demo/  # Angular demo app
│   └── selvans-python-demo/   # FastAPI demo backend
└── docker-compose.yml

Quick Start

One command (recommended)

Dev (Node 18+ + pnpm + Docker):

pnpm run setup

This starts Core (:8080) + Python demo (:8001) + Angular demo (:4200) — all in Docker, including the Angular dev server with live-reload. Open http://localhost:4200 — the selvans-panel should show "connected".

Live-reload: the Angular source is bind-mounted into the container. Saving a file in demos/selvans-angular-demo/ or packages/selvans-angular/ triggers an automatic browser update (~1 s latency due to polling on Docker Desktop Windows).

First startup: the Angular container build (esbuild + pnpm install inside the container) takes 1-3 minutes. pnpm run setup waits up to 180 s for :4200 to respond.

Non-technical / profano (Docker only — no Node/pnpm needed):

# macOS / Linux
./scripts/setup.sh --docker

# Windows
scripts\setup.bat --docker

# Or directly:
docker compose --profile full up --build

Note: the --docker / --profile full path uses the nginx container (selvans-angular-demo, profile full) — a static production-like bundle on :4200. Do not run it together with pnpm run setup (both bind port 4200).

See [[Getting-started]] in the wiki for the full guide, prerequisites per persona, and troubleshooting.

Manual start

1. Start the Core

docker compose up selvans-core
# Admin UI → http://localhost:8080/ui
# MCP SSE  → http://localhost:8080/mcp/sse

2. Integrate the Angular Frontend

npm install selvans-angular

// app.module.ts
import { SelvansModule } from 'selvans-angular';

@NgModule({
  imports: [
    SelvansModule.forRoot({
      coreUrl: 'http://localhost:8080',
      appId: 'my-app'
    })
  ]
})
export class AppModule {}

Mark your components with semantic directives:

<main [SelvansNode]="{ id: 'main', template: 'layout', description: 'Main content area' }">
  <form [SelvansNode]="{ id: 'login-form', template: 'form', description: 'User login form' }">
    <input [SelvansTarget]="'email-input'" type="email" />
    <button [SelvansTarget]="'submit-btn'">Login</button>
  </form>
</main>

3. Integrate the Python Backend

pip install selvans

# main.py
from selvans import SelvansBeApp, SelvansBeConfig, SelvansService, operation

class TaskService(SelvansService):
    name = "tasks"
    description = "Task management"

    @operation("list", description="List tasks, optionally filtered by status")
    async def list_tasks(self, status: str = "") -> list[dict]:
        return await db.list_tasks(status=status)

    @operation("create", description="Create a new task")
    async def create_task(self, title: str, priority: str = "medium") -> dict:
        return await db.create_task(title, priority)

surface = SelvansBeApp(SelvansBeConfig(core_url="http://localhost:8080"))
surface.register(TaskService())
app = surface.create_app()

4. Connect an AI Client

Add the Core's MCP endpoint to your AI client (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "selvans": {
      "url": "http://localhost:8080/mcp/sse"
    }
  }
}

The AI can now observe your app's UI and call your backend operations directly.

Run the Full Demo

pnpm run setup
# → Core :8080 + Python demo :8001 + Angular dev container :4200 (live-reload)

Or all-in-Docker prod-like (no Node required):

docker compose --profile full up --build
# → Core :8080 + Python demo :8001 + Angular nginx :4200 (static bundle)

Note: selvans-angular-dev (dev, live-reload) and selvans-angular-demo (profile full, nginx) both bind port 4200 — do not start them together.

Packages

Built-in Frontend Tools

The Angular library registers these tools automatically:

License

Distributed under the Apache 2.0 license — see LICENSE and NOTICE.