# AI Agent Readiness Audit for MCP & A2A (`suezcanal.xyz/agent-readiness`) Actor

Audit whether an API or repository is ready for machine discovery across OpenAPI, MCP, A2A, and Apify. Returns deterministic READY, PARTIAL, or BLOCKED findings with remediation.

- **URL**: https://apify.com/suezcanal.xyz/agent-readiness.md
- **Developed by:** [Matteo Messina](https://apify.com/suezcanal.xyz) (community)
- **Categories:** AI, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.01 / agent readiness report

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### Audit API and agent readiness before you publish

Agent Readiness is a deterministic audit for developers and teams preparing APIs, repositories, MCP servers, A2A agents, or Apify Actors for machine discovery. It inspects a caller-supplied snapshot and returns a structured readiness report with evidence for every failed check.

Use it when you want a fast answer to questions such as: Is this OpenAPI definition usable by agents? Is the MCP metadata complete? Does the A2A Agent Card expose a clear skill? Is an Apify Actor packaged with the metadata an agent or marketplace expects?

The Actor does not execute repository code and does not use an LLM. The same input produces the same result for the same version of the audit rules.

Main use cases include:

- pre-release checks for API and AI agent infrastructure;
- MCP server readiness audits before registry submission;
- A2A Agent Card and skill metadata checks;
- OpenAPI agent compatibility checks;
- Apify Actor packaging checks;
- CI and release-gate evidence for teams publishing machine-consumable tools.

### What it checks

For OpenAPI, Agent Readiness checks for basic documentation and licensing, an OpenAPI 3.x document, discoverable HTTP operations, stable `operationId` values, useful operation summaries, and declared responses.

For MCP, it checks for discoverable server metadata, a stable identity, a meaningful description, and declared tool metadata. For A2A, it checks for a well-known Agent Card, identity metadata, and declared skills. For Apify, it checks Actor metadata, an input schema, and explicit pricing metadata.

Every failed criterion is returned as a machine-readable finding with a code, severity, evidence path, explanation, and remediation. This makes the readiness report suitable for both humans and automated release workflows.

### Input

Provide a `files` object that maps relative repository paths to UTF-8 text contents, plus one or more `targets`.

```json
{
  "files": {
    "README.md": "# Example API\nUsage documentation",
    "LICENSE": "MIT License",
    "openapi.yaml": "openapi: 3.1.0\ninfo: {title: Example, version: 1.0.0}\npaths: {}"
  },
  "targets": ["openapi"]
}
```

Supported targets are `openapi`, `mcp`, `a2a`, and `apify`. You can request several targets in one audit. The optional `repository_url` is reference metadata only in the current release. The Actor does not clone that repository or fetch private source-control content.

### Output

Each run writes one complete readiness report to the default Apify dataset. A report contains:

- `status`: `READY`, `PARTIAL`, or `BLOCKED`;
- `score`: deterministic readiness score from 0 to 100;
- `findings`: evidence-backed issues and recommended fixes;
- `checks_run`: number of deterministic checks evaluated.

Example:

```json
{
  "status": "BLOCKED",
  "score": 75,
  "findings": [
    {
      "code": "openapi.operations_missing",
      "severity": "error",
      "message": "No HTTP operations were found",
      "evidence": ["openapi.yaml"],
      "remediation": "Define at least one path operation."
    }
  ],
  "checks_run": 5
}
```

Because the output is structured, another agent can consume the readiness report directly and decide whether to continue a deployment, request changes, or route the repository to a human reviewer.

### Pricing

Agent Readiness uses Apify pay-per-event pricing. The initial beta contract charges one `readiness-report` event only when a complete readiness report is written to the default dataset. The introductory event price is USD 0.01 per report.

The price is intentionally simple so developers and agents can test the capability with low friction. Current pricing is always shown by Apify before execution and may be adjusted in future versions as the audit expands.

### Why use a deterministic readiness report

AI infrastructure often fails at the boundary between working code and discoverable, well-described capabilities. A service may run correctly while lacking a stable operation ID, Agent Card, MCP tool description, Actor input schema, or other metadata that allows an external agent to understand and call it reliably.

Agent Readiness treats those interfaces as release requirements. It does not attempt to judge whether your product idea is good. It checks whether the supplied machine-facing artifacts satisfy explicit rules and shows the evidence behind the result.

This makes it useful as an independent readiness gate before publishing to Apify, exposing an MCP server, announcing an A2A agent, or shipping an OpenAPI-based integration.

### Limitations

The current release evaluates caller-supplied text snapshots only. It does not execute code, clone repositories, authenticate to private source control, test live endpoint uptime, perform penetration testing, verify marketplace acceptance, or guarantee protocol certification.

A `READY` result means the supplied snapshot passes the deterministic checks implemented by this Actor version. It is not a security audit, legal review, production availability guarantee, or endorsement by Apify, the MCP project, the A2A project, or any other platform.

Do not include passwords, API keys, private keys, tokens, personal data, or other secrets in the `files` input. Submit only the artifacts needed for the readiness audit.

### Publisher

Agent Readiness is published by suezcanal.xyz as part of its tools program for evidence-driven, machine-consumable decision infrastructure. Public contracts and discovery metadata are maintained separately from the private implementation so integrations can evolve without exposing commercial source code.

# Actor input Schema

## `repository_url` (type: `string`):

Optional canonical repository URL for reference only.

## `files` (type: `object`):

Mapping of relative file paths to UTF-8 text contents. Do not include secrets or credentials.

## `targets` (type: `array`):

List one or more machine-consumption targets: openapi, mcp, a2a, or apify. Values are validated by the Actor runtime.

## Actor input object example

```json
{
  "files": {
    "README.md": "# Example API\nUsage documentation",
    "LICENSE": "MIT License",
    "openapi.yaml": "openapi: 3.1.0\ninfo: {title: Example, version: 1.0.0}\npaths: {}"
  },
  "targets": [
    "openapi"
  ]
}
```

# Actor output Schema

## `results` (type: `string`):

Default dataset items containing READY, PARTIAL, or BLOCKED assessments.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "files": {
        "README.md": "# Example API\nUsage documentation",
        "LICENSE": "MIT License",
        "openapi.yaml": "openapi: 3.1.0\ninfo: {title: Example, version: 1.0.0}\npaths: {}"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("suezcanal.xyz/agent-readiness").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "files": {
        "README.md": """# Example API
Usage documentation""",
        "LICENSE": "MIT License",
        "openapi.yaml": """openapi: 3.1.0
info: {title: Example, version: 1.0.0}
paths: {}""",
    } }

# Run the Actor and wait for it to finish
run = client.actor("suezcanal.xyz/agent-readiness").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "files": {
    "README.md": "# Example API\\nUsage documentation",
    "LICENSE": "MIT License",
    "openapi.yaml": "openapi: 3.1.0\\ninfo: {title: Example, version: 1.0.0}\\npaths: {}"
  }
}' |
apify call suezcanal.xyz/agent-readiness --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,suezcanal.xyz/agent-readiness"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/k9ci7otkB2aGWZfa9/builds/xqFzX7lxaUcfqlYK6/openapi.json