ta-studio-mcp 1.0.3 → 1.0.4

package/README.md

@@ -1,39 +1,59 @@
-# ta-studio-mcp
+# ta-studio-mcp 🚀
 
-**Domain knowledge MCP server for AI agents working on mobile test automation.**
+**The definitive domain knowledge layer for AI agents building mobile test automation at TA Studio.**
 
-One command gives your agent structured knowledge about OAVR navigation patterns, SoM screenshot annotation, coordinate scaling fixes, agent configuration, and 9+ documented bug fixes — so it builds on proven solutions instead of rediscovering them.
+AI agents often struggle with project-specific context, unique navigation patterns, and "tribal knowledge" about past bugs. `ta-studio-mcp` solves this by giving your agent (Claude, Cursor, Windsurf) structured, programmatic access to the team's methodologies, codebase maps, and verified bug fixes.
 
-## Quick Start
+---
+
+## 📋 Prerequisites
+
+- **Node.js**: `v18.0.0` or higher.
+- **MCP Client**: An IDE or tool that supports the [Model Context Protocol](https://modelcontextprotocol.io) (e.g., Claude Desktop, Cursor, Windsurf, or VS Code with an MCP extension).
+
+---
+
+## ⚡ Quick Start
+
+You don't even need to install it locally to test it. Run the following command to see the server in action:
 
 ```bash
 npx ta-studio-mcp
 ```
+*(This will start the server in stdio mode, waiting for a client to connect.)*
+
+---
 
-## What's Inside
+## 🛠 What's Inside?
 
-| Tool | What It Returns |
-|------|----------------|
-| `getMethodology` | 10+ topics: OAVR pattern, SoM annotation, coordinate scaling, agent config, vision click, mobile MCP, flicker detection, closed loop, device auto-select |
-| `getKnownIssues` | 9 documented bugs with symptoms, root causes, fixes, file paths, and commit SHAs |
-| `getCodebaseMap` | Full codebase structure — backend, frontend, agents, scripts, integrations, config |
-| `getWorkflow` | 7 step-by-step workflows: bug_fix, navigation_test, bbox_verify, agent_debug, feature, figma_analysis, flicker_test |
-| `getQuickCommands` | All dev commands for backend, frontend, E2E, device, and git |
-| `getConventions` | Code style guidelines, patterns, and 7 critical rules |
-| `getAgentConfig` | Agent configuration reference — models, parallel_tool_calls, reasoning, streaming |
+Once connected, your agent gains access to these primary tools:
 
-## Installation
+| Tool | Purpose | Beginner Tip |
+|------|---------|---------------|
+| `getMethodology` | Deep dives into OAVR, SoM, Coordinate Scaling, and more. | Ask: *"How does the team handle screen navigation?"* |
+| `getKnownIssues` | A database of 9+ verified bug fixes with root causes. | Ask: *"Are there any known issues with bounding boxes?"* |
+| `getCodebaseMap` | Explains the purpose of every directory and key file. | Ask: *"Where is the device simulation logic located?"* |
+| `getWorkflow` | Step-by-step guides for common tasks (testing, debugging). | Ask: *"Help me run a navigation test from scratch."* |
+| `getConventions` | 7 critical rules and coding style guidelines. | Ask: *"What are the critical rules for backend development?"* |
+| `getAgentConfig` | Reference for model types, reasoning levels, and streaming. | Ask: *"What model should the coordinator agent use?"* |
 
-### Claude Code
+---
 
+## 📦 Installation Guide
+
+### [Claude Desktop](https://claude.ai/download)
+Run this in your terminal to automatically add the server:
 ```bash
 claude mcp add ta-studio -- npx -y ta-studio-mcp
 ```
 
-### Cursor
-
-Add to `.cursor/mcp.json`:
+### [Cursor](https://cursor.com)
+1. Open **Settings** -> **Features** -> **MCP**.
+2. Click **+ Add New MCP Server**.
+3. Name: `ta-studio` | Type: `command` | Command: `npx -y ta-studio-mcp`
 
+### [Windsurf](https://codeium.com/windsurf)
+Add the following to your `~/.codeium/windsurf/mcp_config.json`:
 ```json
 {
   "mcpServers": {
@@ -45,96 +65,44 @@ Add to `.cursor/mcp.json`:
 }
 ```
 
-### Windsurf
+---
 
-Add to `~/.codeium/windsurf/mcp_config.json`:
+## 🧠 Key Knowledge & Expert Implementation
 
-```json
-{
-  "mcpServers": {
-    "ta-studio": {
-      "command": "npx",
-      "args": ["-y", "ta-studio-mcp"]
-    }
-  }
-}
-```
+### 1. Coordinate Scaling (The common "Bbox Bug")
+**The Problem**: Mobile screenshots are compressed to ~45% resolution (486×1080), but XML elements use native coordinates (1080×2400).
+**The Fix**: 
+1. Get native size via `adb shell wm size`.
+2. Parse with regex: `re.search(r'(\d+)\s*x\s*(\d+)', ...)`.
+3. Apply scale factors: `native_x * (screenshot_width / native_width)`.
 
-### VS Code (Copilot / Continue / Augment)
+### 2. Set-of-Mark (SoM) Annotation
+We use a high-performance labeling system:
+- **PIL Threading**: Heavy drawing is offloaded to `asyncio.to_thread` to prevent IDE lag.
+- **TOON Format**: We strip redundant XML metadata (package names, etc.) to reduce LLM token usage by **40%**.
+- **Priority matching**: `radiobutton` is matched before `button` to avoid class collisions.
 
-Add to `.vscode/settings.json`:
+### 3. Flicker Detection (4-Layer Pipeline)
+How we catch 16ms UI glitches:
+1. **Trigger**: High-speed `adb screenrecord`.
+2. **Extraction**: `ffmpeg` scene filtering (`gt(scene,0.003)`).
+3. **Analysis**: SSIM similarity checks between frames.
+4. **Verification**: GPT-5.2 Vision confirms the glitch.
 
-```json
-{
-  "mcp": {
-    "servers": {
-      "ta-studio": {
-        "command": "npx",
-        "args": ["-y", "ta-studio-mcp"]
-      }
-    }
-  }
-}
-```
-
-## Example Usage
-
-Ask your AI agent:
-
-- *"How does the OAVR pattern work?"* → Agent calls `getMethodology({ topic: "oavr" })`
-- *"What's the bounding box coordinate bug?"* → Agent calls `getKnownIssues({ category: "bbox_alignment" })`
-- *"How do I debug a navigation test?"* → Agent calls `getWorkflow({ name: "agent_debug" })`
-- *"What model does the coordinator use?"* → Agent calls `getAgentConfig()`
-
-## Key Knowledge Areas
-
-### Coordinate Scaling (Critical Fix)
-
-Mobile MCP screenshots are JPEG-compressed at ~45% of native resolution (486×1080 vs 1080×2400), but element coordinates from `list_elements_on_screen` are in native space. The fix involves parsing the native resolution and applying scale factors:
-
-- **Regex**: `re.search(r'(\d+)\s*x\s*(\d+)', get_screen_size())`
-- **Scaling**: `target_x = raw_x * (img_width / screen_width)`
-
-### Set-of-Mark (SoM) Annotation
-
-The server provides methodology for high-performance screenshot tagging:
-- **PIL Threading**: Uses `asyncio.to_thread` for CPU-intensive drawing to keep the event loop responsive.
-- **TOON Format**: Token Optimized Object Notation strips 40% of redundant metadata from screen hierarchies before LLM processing.
-- **Priority Logic**: Class matching for `radiobutton` is prioritized over `button` to prevent classification collisions.
+---
 
-### Flicker Detection (4-Layer)
-
-1. **Trigger**: `adb shell screenrecord`
-2. **Extraction**: `ffmpeg -vf "select='gt(scene,0.003)'"`
-3. **Analysis**: SSIM (Structural Similarity Index) pairs
-4. **LLM**: GPT-5.2 Vision verification
-
-### Agent Configuration
-
-| Agent | Model | parallel_tool_calls | Reasoning | Why? |
-|-------|-------|-------------------|-----------|------|
-| Coordinator | gpt-5.2 | `true` | high | Orchestration tasks can run in parallel. |
-| Device Testing | gpt-5-mini | `false` | medium | Navigation is sequential; parallel calls cause session race conditions. |
-
-
-## Tech Stack
-
-- **Runtime**: Node.js ≥ 18
-- **Protocol**: Model Context Protocol (MCP) via `@modelcontextprotocol/sdk`
-- **Transport**: stdio (local process)
-- **Schema**: Zod validation
-
-## Development
-
-```bash
-cd packages/ta-studio-mcp
-npm install
-npm run build    # Compile TypeScript
-npm run dev      # Watch mode
-npm start        # Run server
-```
+## 👩‍💻 For Developers: Contributing Knowledge
 
-## License
+If you find a new bug or develop a new pattern, update the local knowledge base:
 
-MIT — see [LICENSE](./LICENSE)
+1. **Add a methodology topic**: Edit `src/knowledge/methodology.ts`.
+2. **Log a bug**: Add to `src/knowledge/known-issues.ts` with the symptom and fix.
+3. **Build & Test**:
+   ```bash
+   npm run build
+   # Test locally with a tool like mcp-inspector
+   npx @modelcontextprotocol/inspector dist/index.js
+   ```
 
+## 📜 License
+MIT © 2026 TA Studios. Build on it. Improve it. 🚀

package/dist/index.js

@@ -14,7 +14,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { registerAllTools } from './tools/register-all.js';
 const server = new McpServer({
     name: 'ta-studio-mcp',
-    version: '1.0.3',
+    version: '1.0.4',
 }, {
     capabilities: {
         logging: {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ta-studio-mcp",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "TA Studio MCP — Domain knowledge, patterns, bug fixes, and workflows for AI agents working on the TA Studio mobile test automation platform.",
   "type": "module",
   "bin": {