AnimaWatch MCP server
2026년 11월 13일 커밋AI 비전과 Playwright 브라우저 녹화를 사용하여 웹 애니메이션의 끊김(jank), 버벅임 및 시각적 아티팩트를 감지합니다.
다른 이름 rishitank/animawatch
- 스타
- 0
- Tools
- 11
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 13일
- 라이선스
- MIT
AnimaWatch MCP란?
AI 비전과 Playwright 브라우저 녹화를 사용하여 웹 애니메이션의 끊김(jank), 버벅임 및 시각적 아티팩트를 감지합니다. 11개 도구를 제공합니다. 예: analyze_fps, watch, watch_with_device.
프로젝트 README에서 생성된 요약
AnimaWatch MCP server 정보
AnimaWatch는 프론트엔드 개발자와 테스터가 AI 클라이언트 내부에서 웹 애니메이션의 끊김, 버벅임 및 시각적 아티팩트를 감지할 수 있도록 지원합니다. Playwright를 사용하여 브라우저 상호작용을 비디오로 녹화한 다음, 비전 AI를 활용하여 타이밍 문제나 시각적 오류를 검사합니다. 사용자는 API 키를 통해 Gemini 2.0 Flash 무료 티어를 사용하거나, qwen2.5-vl:7b와 같은 모델을 사용하여 Ollama로 프로세스를 완전히 로컬에서 실행하는 방식 중 선택할 수 있습니다.
개발자는 watch, screenshot, check_accessibility와 같은 특정 도구를 통해 MCP server와 상호작용합니다. 시스템은 상호작용을 녹화하거나, 기존 비디오 파일을 분석하거나, 정적 페이지 분석을 수행할 수 있습니다. 또한 전용 MCP resource를 통해 저장된 녹화물과 분석 결과에 접근할 수 있습니다. 이러한 설정은 사람이 화면을 관찰하는 방식을 모방하여 모달 전환이나 스크롤 부드러움과 같은 복잡한 UI 동작에 대한 자동화된 시각적 테스트를 가능하게 합니다.
활용 사례
- 1애니메이션 버벅임 진단AI에게 특정 UI 전환을 관찰하도록 요청하여 끊김이 발생하는 정확한 타임스탬프를 찾습니다.
- 2대화형 UI 요소 검증클라이언트에게 메뉴를 클릭하도록 지시하고, 그 결과로 나타나는 슬라이드 인 애니메이션의 부드러움을 모니터링합니다.
- 3시각적 접근성 감사 수행웹페이지에 대한 검사를 요청하여 시각적 분석을 통해 대비와 가독성을 평가합니다.
- 4기존 비디오 녹화물 분석이전에 녹화된 비디오 파일을 서버에 제출하여 자동화된 시각적 검사를 수행합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
AnimaWatch MCP 도구 11
README에서 감지됨analyze_fpswatchwatch_with_devicescreenshotget_performance_metricscompare_screenshotslist_devicescheck_accessibilityanalyze_with_consensus_toolanalyze_videorecord
| analyze_fps | — | |
| watch | — | |
| watch_with_device | — | |
| screenshot | — | |
| get_performance_metrics | — | |
| compare_screenshots | — | |
| list_devices | — | |
| check_accessibility | — | |
| analyze_with_consensus_tool | — | |
| analyze_video | — | |
| record | — |
구성
GEMINI_API_KEYOLLAMA_MODELVISION_PROVIDER
| 이름 | 설명 | 유형 |
|---|---|---|
| GEMINI_API_KEY | — | |
| OLLAMA_MODEL | — | |
| VISION_PROVIDER | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능rishitank/animawatch is public and reachablegithub.com/rishitank/animawatch ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-13github.com/rishitank/animawatch ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음11 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기🎬 AnimaWatch
An MCP server that checks web animations the way a tester would. It measures dropped frames inside the page, and it can look at a recording with AI vision to find visual glitches.
AnimaWatch is built with FastMCP from the official MCP Python SDK.
✨ What It Does
YOU: "Check the menu animation on this page for jank"
↓
ANIMAWATCH:
1. Opens the page in Chromium and measures every frame in the page
(requestAnimationFrame + Long Animation Frames), against the
display's real refresh rate
2. Optionally records the interaction and asks a vision model
(Gemini with your own key, or Ollama locally) what looks wrong
↓
RESULT: "18.4% of frames dropped. A 104 ms long animation frame at 1.3s
came from blockMainThread (app.js). The menu text overlaps the logo
while it slides in."
How it measures jank
Frame timing comes from inside the page, not from the video:
requestAnimationFrametimestamps. A gap of n refresh intervals between two frames means n − 1 dropped frames. The jank percentage is the share of the display's refreshes that got no new frame.- The refresh interval is measured. Before each page loads, AnimaWatch samples the blank tab in the same browser, so it judges a 120 Hz display at 120 Hz. You can also set the rate yourself.
- Long Animation Frames API (Chromium 123+). It lists frames over 50 ms and the script, and where possible the function, that held each one up.
- Compositor frames (optional,
trace_compositor). Chromium's own per-frame verdicts come from a DevTools trace. A CSStransformoropacityanimation runs on the compositor and can stay smooth while the main thread is blocked. The trace shows the difference. - Page load is not counted. Measurement starts once the network is idle.
The video is used only for the vision pass. Playwright records it at a fixed 25 fps, so frame gaps in the video say nothing about the page's frame rate. Versions up to 0.3.1 measured jank from the video, and a perfectly smooth animation scored 98.8% jank there. That method has been removed.
🚀 Features
| Feature | Description |
|---|---|
| 🎯 Frame timing | Dropped frames, frame-time percentiles and long animation frames, measured in the page. No AI or API key needed. |
| 👁️ AI vision | Gemini (your own API key) or Ollama (local) reviews recordings and screenshots for visual problems |
| 📱 Device emulation | iPhone, Pixel, iPad and desktop profiles |
| 📊 Core Web Vitals | LCP, FCP, CLS (largest session window) and TTFB |
| 🔍 Visual diff | Pixel comparison of two pages |
| ♿ Accessibility checks | Visual accessibility review (contrast, readability); needs vision |
| 💾 Resources | Recordings and analyses as MCP resources |
| 📝 Prompts | Prompt templates for animation, page and accessibility reviews |
🛠️ MCP Capabilities
Tools
| Tool | Description | Needs vision |
|---|---|---|
analyze_fps |
🎯 Dropped frames and long animation frames for a URL, after optional actions | No |
watch |
🎬 Frame timing, plus a vision review of the recording | Optional |
watch_with_device |
📱 watch with device emulation |
Optional |
screenshot |
📸 Screenshot, with a vision review when vision is on | Optional |
get_performance_metrics |
📊 Core Web Vitals and page-load numbers | No |
compare_screenshots |
🔍 Pixel diff between two URLs | No |
list_devices |
📱 Device profiles | No |
check_accessibility |
♿ Visual accessibility review | Yes |
analyze_with_consensus_tool |
🤝 Gemini and Ollama review the same screenshot, and the findings they agree on are reported (not offered when hosted) | Yes (both) |
analyze_video |
🎥 Vision review of a local video file (not offered when hosted) | Yes |
record |
⏺️ Record without analysis, saving to a local folder (not offered when hosted) | No |
Actions (click, hover, type, scroll and wait) are passed as a list, for example [{"type": "click", "selector": "#menu"}]. They are validated before any page opens: an unknown action or a missing selector is an error, not a skipped step. Only http and https URLs are opened, plus file:// on a local install. Each wait is capped at MAX_RECORDING_DURATION seconds.
Resources
| URI | Description |
|---|---|
animawatch://recordings/{id} |
Stored video recordings |
animawatch://analyses/{id} |
Stored analysis results |
animawatch://config |
Current server configuration (never the API key) |
Prompts
| Prompt | Description |
|---|---|
animation_diagnosis |
Animation review template |
page_analysis |
Static page review template |
accessibility_check |
Accessibility review template |
🚀 Quick Start
1. Install
git clone https://github.com/rishitank/animawatch.git
cd animawatch
uv sync
uv run playwright install chromium
2. Choose a vision option (optional)
Frame timing, Core Web Vitals, screenshots and diffs work without any of these.
- Gemini, with your own API key. Create a key in Google AI Studio and set
GEMINI_API_KEY. See Cost before you rely on the free tier. - Ollama, on your own machine. See Local vision with Ollama.
- None. Set
VISION_PROVIDER=none. AnimaWatch also runs without vision when Gemini has no key.
3. Configure
cp .env.example .env
# Edit .env if you use Gemini or Ollama
4. Add to Your MCP Client
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"animawatch": {
"command": "uv",
"args": ["--directory", "/path/to/animawatch", "run", "animawatch"],
"env": {
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}
Other MCP clients take the same command and arguments. To serve over streamable HTTP instead of stdio, run uv run animawatch --http. It listens on SERVER_HOST:SERVER_PORT (default 127.0.0.1:8765) at /mcp. It accepts only localhost, the bind address and the names in ALLOWED_HOSTS in Host and Origin headers, which protects it against DNS rebinding. The HTTP transport has no authentication, so do not expose it beyond your machine without a proxy that adds it.
📖 Usage Examples
"Measure the frame rate of https://example.com while the carousel runs"
"Click #hamburger on https://example.com and watch the slide-in animation"
"Watch https://example.com on an iPhone 15 Pro with focus on scroll behaviour"
"Check accessibility on https://example.com"
"Show me the analysis from animawatch://analyses/abc123"
🔧 Configuration
| Environment Variable | Default | Description |
|---|---|---|
VISION_PROVIDER |
gemini |
gemini, ollama or none |
GEMINI_API_KEY |
(none) | Your own Gemini API key. Without it, vision is off. |
VISION_MODEL |
gemini-3.8-flash |
The Gemini model. It must accept video. |
OLLAMA_HOST |
http://localhost:11434 |
Ollama server |
OLLAMA_MODEL |
qwen2.5-vl:7b |
The Ollama vision model |
REFRESH_RATE_HZ |
measured | The refresh rate to judge frames against |
BROWSER_HEADLESS |
true |
Run the browser headless |
BROWSER_EXECUTABLE_PATH |
(Playwright's) | Launch this Chromium instead of Playwright's bundled one |
ALLOW_FILE_URLS |
true |
Allow file:// URLs |
VIDEO_WIDTH / VIDEO_HEIGHT |
1280 / 720 |
Viewport and recording size |
MAX_RECORDING_DURATION |
30 |
Upper bound in seconds on every wait |
SERVER_HOST / SERVER_PORT |
127.0.0.1 / 8765 |
Bind address for --http |
ALLOWED_HOSTS |
(none) | Extra host names, comma-separated, that --http accepts in Host and Origin headers, for example a reverse proxy's domain |
The default model was checked on 13 Nov 2026. Google retired gemini-2.0-flash, the previous default, on 1 Jun 2026, and lists gemini-3.8-flash as stable with video input (models, deprecations).
💰 Cost
AnimaWatch is open source (MIT), and frame timing needs no paid service. The vision pass is the only part that can cost money:
| Option | What you pay |
|---|---|
| No vision | Nothing beyond your own machine |
| Ollama | Nothing to a provider. It runs on your hardware, and a 7B vision model needs a capable machine. |
| Gemini | Google bills your key according to Gemini API pricing. Video input uses far more tokens than a screenshot. |
About Gemini's free tier. Google offers free quota with rate limits. However, the Gemini API Additional Terms (last updated 28 April 2026) say: "You may use only Paid Services when making API Clients available to users in the European Economic Area, Switzerland, or the United Kingdom." So if you make an app built on AnimaWatch available to users in the UK, the EEA or Switzerland, use a paid (billing-enabled) Gemini key, or use Ollama or no vision. This is a summary, not legal advice.
🏠 Local vision with Ollama
# Install and start Ollama (https://ollama.com)
ollama serve
ollama pull qwen2.5-vl:7b
# AnimaWatch needs the ollama extra, and ffmpeg for video
uv sync --extra ollama
export VISION_PROVIDER=ollama
export OLLAMA_MODEL=qwen2.5-vl:7b
Ollama's vision models take images, not video. For watch and analyze_video, AnimaWatch therefore takes 8 frames spread across the whole recording and reviews each one. This needs ffmpeg and ffprobe on your PATH. The model sees still frames, not motion. Frame timing is measured in the page either way.
☁️ Apify Actor (single-tenant Standby)
The repository includes an Apify Actor definition. Nothing is published yet.
.actor/actor.jsonturns on Standby mode, with the MCP server atwebServerMcpPath: /mcp.- The
Dockerfileis based onapify/actor-python-playwrightand keeps that image's Playwright version, so the bundled browsers match. .actor/input_schema.jsonholds the user's own Gemini key, as a secret field. Without a key, vision is off..actor/pay_per_event.jsondefines one event,page-analysed, charged once for each page a tool loads and analyses. $0.05 is a proposed price, not a final one.- It is designed to be single-tenant. Each user's server runs in that user's own Apify account, so the user pays the platform compute plus the events, and nothing is shared between users. Hosted, it refuses
file://URLs, does not offeranalyze_video,recordoranalyze_with_consensus_tool(there is no Ollama), and writes no diff images. With vision turned off, any key in the input is dropped. - Known limitation: the hosted browser will open any
http(s)address, including private or loopback ones. Single-tenancy limits that to the caller's own run. A multi-tenant mode would first need request interception that blocks private addresses on every request, redirects included.
Run it locally with uv pip install 'apify>=4.0.0,<5', then uv run animawatch-actor. Set ACTOR_TEST_PAY_PER_EVENT=true to log charges to a local dataset.
🏗️ Architecture
┌──────────────────────────────────────────────────────────────┐
│ AnimaWatch │
│ (FastMCP server) │
├──────────────────────────────────────────────────────────────┤
│ Lifespan context (one per server, shared by all sessions) │
│ ├── BrowserRecorder (Playwright Chromium) │
│ │ ├── in-page frame collector (rAF + LoAF) │
│ │ ├── optional CDP trace (compositor frames) │
│ │ └── video recording (vision pass only) │
│ ├── VisionProvider: Gemini | Ollama | none │
│ └── recordings / analyses │
├──────────────────────────────────────────────────────────────┤
│ Tools: analyze_fps, watch, watch_with_device, screenshot, │
│ get_performance_metrics, compare_screenshots, ... │
│ Resources: animawatch://recordings, analyses, config │
│ Prompts: animation_diagnosis, page_analysis, accessibility │
├──────────────────────────────────────────────────────────────┤
│ Transports: stdio | streamable HTTP (/mcp) | Apify Standby │
└──────────────────────────────────────────────────────────────┘
🧪 Development
uv sync --all-extras
uv run playwright install chromium
uv run pytest # includes tests that drive a real Chromium
uv run ruff check . && uv run mypy src/
The frame-timing regression tests open real pages in Chromium. A smooth CSS animation must score under 2% jank. A page that blocks its main thread for 100 ms every 150 ms must score over 30%. To use a Chromium installed elsewhere, set BROWSER_EXECUTABLE_PATH.
📄 License
MIT
AnimaWatch MCP 질문
AnimaWatch MCP는 어떤 도구를 제공하나요?
11개 도구를 제공합니다. 예: analyze_fps, watch, watch_with_device, screenshot, get_performance_metrics.
AnimaWatch는 애니메이션 문제를 어떻게 감지하나요?
Playwright를 사용하여 브라우저 상호작용을 비디오로 녹화한 후, Gemini 또는 Ollama와 같은 Vision AI로 비디오를 전송하여 끊김과 버벅임을 분석합니다.
이 도구는 접근성 테스트를 지원하나요?
네, 대비 및 가독성 확인과 같은 시각적 접근성 분석 도구를 포함하고 있습니다.
Gemini 사용 시 발생하는 비용은 얼마인가요?
AI Studio를 통해 Gemini를 사용하는 경우 특정 제한(분당 15회 요청 및 일일 1M 토큰) 내에서 무료로 사용할 수 있습니다.