Skip to content

AGENTS.md

Latest commit

 

History

History
162 lines (119 loc) · 6.73 KB

AGENTS.md

File metadata and controls

162 lines (119 loc) · 6.73 KB

AGENTS.md

Project Overview

MCP server for Tauri v2 application development. Provides tools for CLI execution, configuration management, mobile device/emulator management, native UI automation, and debugging.

Monorepo packages:

  • packages/mcp-server/ - Main MCP server implementation
  • packages/tauri-plugin-mcp-bridge/ - Tauri plugin for automation bridge (Rust)
  • packages/test-app/ - Test application for E2E testing
  • packages/cli - A CLI wrapper for the MCP server funcionality

Setup Commands

npm install              # Install all dependencies
npm run build            # Build all packages
npm test                 # Run tests (requires build first)
npm run standards        # Run commitlint + eslint

Code Style

  • TypeScript: Strict mode, ESM with .js extensions in imports, ES2022 target
  • Naming: camelCase for functions/variables, PascalCase for classes, kebab-case for files
  • Acronyms: All lowercase or all caps, never mixed (e.g., url or URL, never Url)
  • Avoid: any type, magic numbers, deeply nested blocks
  • Prefer: Early returns, higher-order functions, immutability (readonly, as const)
  • Functions: Arrow for simple (<3 instructions), named otherwise; use RO-RO pattern
  • JSDoc: Document public classes and methods

Adding New MCP Tools

All tools are defined in packages/mcp-server/src/tools-registry.ts:

  1. Add Zod schema + handler in the appropriate module (manager/, driver/, monitor/)
  2. Import and add entry to TOOLS array in tools-registry.ts
  3. Add E2E test in packages/mcp-server/tests/e2e/

Tool categories: PROJECT_MANAGEMENT, MOBILE_DEVELOPMENT, UI_AUTOMATION, IPC_PLUGIN

Testing Instructions

  • Always build before testing: npm run build
  • E2E tests launch test-app and connect via WebSocket
  • Tests located in packages/mcp-server/tests/e2e/
  • Prefer E2E tests over unit tests
  • CI timeout is 8 minutes; local is 1 minute

Session Management

  • Call driver_session with action: 'start' before using driver tools
  • Always call with action: 'stop' to clean up
  • WebSocket port range: 9223-9322

Git Commits

Follow: https://raw.githubusercontent.com/silvermine/standardization/refs/heads/master/commitlint.js

Releasing

This monorepo uses a single version across all packages. All packages share the same version number.

Files to Update

Version files (all must have the same version):

  • packages/mcp-server/package.json - version field
  • packages/cli/package.json - version field and @hypothesi/tauri-mcp-server dependency version
  • packages/cli/.claude-plugin/plugin.json - version field
  • gemini-extension.json - version field
  • packages/tauri-plugin-mcp-bridge/package.json - version field
  • packages/tauri-plugin-mcp-bridge/Cargo.toml - version field

Changelog files (all four must be updated):

  • CHANGELOG.md - Root changelog for overall project history
  • packages/cli/CHANGELOG.md - CLI-specific changes
  • packages/mcp-server/CHANGELOG.md - Server-specific changes
  • packages/tauri-plugin-mcp-bridge/CHANGELOG.md - Plugin-specific changes

Lock files (updated automatically but must be committed):

  • package-lock.json - Updated by npm install
  • packages/tauri-plugin-mcp-bridge/Cargo.lock - Updated by cargo update
  • packages/test-app/src-tauri/Cargo.lock - Updated by cargo update

Release Checklist

  1. Review git log to identify changes since the last release tag

  2. Determine version bump (patch for fixes, minor for features, major for breaking)

  3. Update all four changelogs with the new version entry:

    • Add entry under ## [Unreleased] with the new version and date
    • Include changes relevant to each package (use _No changes to this package._ if none)
    • Do not skip any version numbers - if v0.2.1 exists, the next must be v0.2.2, not v0.2.3

  4. Update version in package.json files using npm (without git tag):

    npm version <version> --no-git-tag-version -w @hypothesi/tauri-mcp-server -w @hypothesi/tauri-mcp-cli -w @hypothesi/tauri-plugin-mcp-bridge

  5. Update version-coupled metadata manually to match:

    • packages/cli/package.json - update the @hypothesi/tauri-mcp-server dependency version
    • packages/cli/.claude-plugin/plugin.json
    • gemini-extension.json
    • packages/tauri-plugin-mcp-bridge/Cargo.toml

  6. Update lock files:

    npm install
cargo update --package tauri-plugin-mcp-bridge  # in packages/tauri-plugin-mcp-bridge/
cargo update --package tauri-plugin-mcp-bridge  # in packages/test-app/src-tauri/

  7. Verify versions in manifests and lock files match the new version:

    grep -n '"version"' packages/cli/.claude-plugin/plugin.json gemini-extension.json
grep -n '"@hypothesi/tauri-mcp-server"' packages/cli/package.json
grep -A2 '"@hypothesi/tauri-mcp-server"' package-lock.json | head -3
grep -A2 '"@hypothesi/tauri-mcp-cli"' package-lock.json | head -3
grep -A2 '"@hypothesi/tauri-plugin-mcp-bridge"' package-lock.json | head -3

  8. Stage all changed files:

    • All four changelogs
    • packages/mcp-server/package.json
    • packages/cli/package.json
    • packages/cli/.claude-plugin/plugin.json
    • gemini-extension.json
    • packages/tauri-plugin-mcp-bridge/package.json
    • packages/tauri-plugin-mcp-bridge/Cargo.toml
    • package-lock.json
    • Both Cargo.lock files

  9. Commit: git commit -m "chore: version bump: v<version>"

  10. Create signed tag: git tag -s v<version> -m "Release v<version>"

  11. Push: git push && git push --tags

Common Mistakes to Avoid

  • Skipping changelog entries: Every version must have an entry in all four changelogs
  • Forgetting lock files: Both package-lock.json and both Cargo.lock files must be updated
  • Forgetting CLI metadata: packages/cli/.claude-plugin/plugin.json, gemini-extension.json, and the CLI's pinned @hypothesi/tauri-mcp-server dependency must match the release version
  • Version mismatch: All version fields must match exactly
  • Missing intermediate versions: If changelogs are missing entries for previous versions, add them before creating the new release

Rust Code

Run cargo fmt and cargo clippy after changes in packages/tauri-plugin-mcp-bridge/.

NPM Dependencies

Always use --save-exact flag when installing.

Key Files

  • packages/mcp-server/src/tools-registry.ts - Single source of truth for all MCP tools
  • packages/mcp-server/src/index.ts - MCP server entry point
  • packages/mcp-server/src/driver/session-manager.ts - WebSocket session management
  • packages/tauri-plugin-mcp-bridge/src/lib.rs - Plugin entry point and WebSocket server setup
  • specs/ - Architecture docs, release process, and design decisions