DOCSEARCHbyAlgolia
Submit Docs

Argos Visual Testing Platform

repository·main·Indexed 20 days ago

https://github.com/argos-ci/argos

An open source visual testing platform for automating and managing visual regressions. Includes documentation on the REST API for build creation and finalization, the Argos MCP (Model Context Protocol) server for AI agent integration, and a comprehensive OAuth 2.1 implementation featuring PKCE, opaque tokens, and scope enforcement.

Tokens
23.2K
Snippets
83
Records
104
Agent score
70%

What's inside Argos

  1. Overview of the Argos MCP Server

    main

    The Argos MCP (Model Context Protocol) server exposes the Argos public REST API to AI agents. It allows AI agents to interact with Argos features by converting existing API operations into MCP tools.

    Key details:

    • Production URL: https://mcp.argos-ci.com (served on its own subdomain).
    • Authentication: Supports Personal Access Tokens (PAT) and OAuth 2.1 access tokens.
    • Note: Project tokens are not supported and will be rejected.
    • Automatic Tool Generation: Any REST endpoint that is eligible for PAT or OAuth authentication is automatically exposed as an MCP tool. The tool name corresponds to the API's operationId.

  2. Authenticate with the Argos MCP Server

    main

    The MCP server uses standard bearer token authentication.

    Supported Token Types

    • Personal Access Tokens (PAT)
    • OAuth 2.1 access tokens

    OAuth Flow

    If a request is made without a valid token, the server returns a 401 status with a WWW-Authenticate header pointing to the .well-known/oauth-protected-resource. This is designed to trigger the MCP client's standard authorization flow (Discovery $\rightarrow$ Dynamic Client Registration $\rightarrow$ Consent).

    Scope Enforcement

    OAuth scopes are enforced at the API layer for every tool call. If a tool call fails due to insufficient scopes, the error is returned as an isError tool result rather than an HTTP 401, allowing the client to handle the error without unnecessary re-authentication.

  3. Authenticate the Argos CLI with ARGOS_TOKEN

    main

    To integrate Argos into your CI environment and publish screenshots, you must provide an ARGOS_TOKEN. This token associates the uploaded screenshots with your specific Argos project.

    Note: The Argos SDKs are maintained in a separate repository: argos-ci/argos-javascript.

  4. How MCP Clients handle Authorization

    main

    Model Context Protocol (MCP) clients discover Argos capabilities via metadata documents and register using Dynamic Client Registration (DCR).

    When an MCP client encounters an unauthorized request (401), the Resource Server (RS) provides the location of the protected resource metadata via the WWW-Authenticate header:

    WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource"

    Well-known agents (such as Claude, Codex, Cursor, or VS Code) are matched against a curated registry (known-apps.ts) to receive a verified badge and official logo. Self-asserted metadata does not grant verification.

  5. Use Parallel Mode for screenshot uploads

    main

    Parallel mode allows a client to upload screenshots in multiple batches. To use this mode, the client must include the parallel parameter set to true during the build creation phase.

    When parallel is true, the following parameters are required:

    • parallelTotal: The total number of upload batches (typically corresponding to the number of parallel workers).
    • parallelNonce: The unique identifier (nonce) for the current upload batch.

  6. Understand the Argos Architecture

    main

    Argos is a visual testing platform designed to compare screenshots and detect UI regressions. The architecture is service-oriented and consists of several key components:

    • Node.js Backend: A GraphQL-based server that handles authentication, project/build logic, and screenshot-diff coordination. It uses a background job system for image processing and notifications.
    • React Frontend: A Single Page Application (SPA) that provides dashboards for viewing project statuses and performing screenshot comparisons.
    • Screenshot Management: Screenshots are stored in AWS S3. The backend fetches these images to perform diffing via dedicated modules (e.g., screenshot-diff/).
    • Data Layer: Uses PostgreSQL for persistence, managed via knex migrations.
    • CLI & SDKs: Used to publish screenshots from CI environments. The CLI requires an ARGOS_TOKEN to associate screenshots with the correct project.

  7. Understand the Argos OAuth 2.1 Authorization and Resource Server model

    main

    Argos acts as both an Authorization Server (AS) and a Resource Server (RS). It follows the OAuth 2.1 standard and the MCP authorization spec.

    Key Security Properties

    • Opaque Tokens: Tokens are not JWTs; they are opaque and hashed at rest.
    • Scope Narrowing: Every request re-validates the token's scope against the user's current membership. An OAuth scope can only narrow permissions; it cannot grant permissions the user does not already possess.
    • Mandatory PKCE: Proof Key for Code Exchange (S256) is required for all authorization code flows.
    • Token Lifecycle: Access tokens are short-lived (1 hour). Refresh tokens are rotated; attempting to reuse a rotated refresh token will revoke the entire grant.

  8. Build Argos for Production

    main

    To compile and optimize both backend and frontend assets for production, use the following command:

    pnpm run build

    When deploying to Heroku, the platform automatically triggers pnpm run heroku-postbuild (which executes the build script) before deployment.

  9. Implement CLI Login using Loopback Authorization Code + PKCE

    main

    The argos-cli is a first-party public client (client_id=argos-cli) that uses the RFC 8252 loopback pattern.

    1. Authorization Request

    The client generates a code_verifier and code_challenge (S256), starts a local server on an ephemeral port, and directs the user to:

    {server.url}/oauth/authorize?response_type=code&client_id=argos-cli
  &redirect_uri=http://127.0.0.1:<port>/callback
  &scope=profile%20projects:read&state=<random>&code_challenge=<challenge>
  &code_challenge_method=S256

    2. Token Exchange

    After the user approves consent and is redirected to the loopback URI, the client exchanges the code for tokens:

    POST {server.url}/oauth/token

grant_type=authorization_code&
code=<code>&
redirect_uri=http://127.0.0.1:<port>/callback&
client_id=argos-cli&
code_verifier=<verifier>

    3. Using and Refreshing Tokens

    • API Calls: Include the token in the header: Authorization: Bearer <access_token>.
    • Refreshing: When the access token expires, use grant_type=refresh_token. Note: The response will rotate the refresh token; you must persist the new refresh token returned in the response.
    POST {server.url}/oauth/token

grant_type=authorization_code&code=<code>
  &redirect_uri=http://127.0.0.1:<port>/callback
  &client_id=argos-cli&code_verifier=<verifier>

  10. Set up Argos MCP for local development

    main

    To use the Argos MCP server locally, you must ensure your local environment can resolve the MCP subdomain and that you have the correct transport configured.

    1. Host Configuration: Add mcp.argos-ci.dev to your /etc/hosts file so it resolves to your local backend.
    2. Headers: Requests must include Accept: application/json, text/event-stream (this is enforced by the MCP SDK transport).
    3. Claude Desktop Integration: Use the following command to add the Argos MCP server to Claude:
    claude mcp add --transport http argos https://mcp.argos-ci.dev:4001

  11. Use the knex-scripts CLI to manage PostgreSQL databases

    main

    The knex-scripts CLI is a tool for managing PostgreSQL databases using Knex.js. It provides commands for database lifecycle management, including creating, dropping, dumping, loading, truncating, and checking database structure.

    If you run the CLI without any arguments, it will display the help menu.

    # Example: View help
$ knex-scripts --help

  12. Discover and read Argos agent skills via MCP resources

    main

    Argos exposes its published agent skills (the same ones installed via npx skills add) as MCP resources. An MCP client can discover these skills using the resources/list method and read their documentation via resources/read.

    • Resource Template: The skills are available under the skill resource type.
    • URI Pattern: Skills are identified by a URI following the pattern: {appOrigin}/.well-known/agent-skills/{skill_name}/SKILL.md.
    • Format: Skill documentation is provided as text/markdown.

    This allows AI agents to dynamically discover capabilities and read the specific instructions required to execute them.