Project tools
Fourteen tools for the project — the unit that owns pages, journeys, audits, and tickets — for its accessibility widget’s settings, and for its personas, the test accounts its journeys sign in as.
list_projects
Section titled “list_projects”List projects in an organization.
| Name | Type | Required | Notes |
|---|---|---|---|
organization_id | string | yes | |
first | number | no | Page size. Default 20. |
after | string | no | Opaque cursor from a prior page’s endCursor. |
Returns: { totalCount, pageInfo, projects }. pageInfo carries hasNextPage and endCursor.
Each projects entry carries id, name, type, description, domain, bundleId,
pageCount, createdAt and updatedAt — so one page tells a mobile project from a web one
without a get_project per row.
Returns an error block if your credential cannot reach that organization.
get_project
Section titled “get_project”Get a single project by ID with details.
| Name | Type | Required |
|---|---|---|
project_id | string | yes |
Returns: the project — id, name, type, description, domain, bundleId,
egressCountry, pageCount, plan, createdAt, updatedAt, its organization, and a pages
total. type and bundleId are
the same pair create_project and update_project return, so a project read back carries the
identity it was stored with.
create_project
Section titled “create_project”Create a new project in an organization.
| Name | Type | Required | Notes |
|---|---|---|---|
organization_id | string | yes | |
name | string | yes | |
domain | string | for a web type | e.g. https://example.com. Discarded for a platform that has no URL. |
description | string | no | |
type | enum | no | Platform being audited. web | ios | android. Default web. |
bundle_id | string | for an ios or android type | The app identifier of the build to audit. Discarded for a platform that has no identifier. The parameter’s own description carries each platform’s grammar. |
use_cases | enum[] | no | At least one of usability | ci | altText. Default ["usability"]. |
egress_country | us | tr | no | The country the project’s cloud audits reach its site from, its free starter scan included. Default us. See update_project for each country’s address. |
type and use_cases are required server-side; omit them and web / ["usability"] are sent. See
Vocabularies.
A project’s identity depends on its platform, and the tool refuses a create that cannot carry one:
an ios or android project with no bundle_id is refused before anything is written, and a web
project with no domain is refused by the server. Neither returns a project.
Returns: the created project — including its type, bundleId and egressCountry, so you can
read back what was actually stored.
update_project
Section titled “update_project”Update an existing project’s name, description, URL, app identifier, platform, bot-protection token, or the country its cloud audits come from.
| Name | Type | Required |
|---|---|---|
id | string | yes |
name | string | no |
description | string | no |
domain | string | no |
bundleId | string | no |
egressCountry | us | tr | no |
type | web | ios | android | no |
botProtectionToken | string | no |
Use the global project ID returned by the read tools. Only the fields you pass are changed. Omitting a field leaves it alone. Passing null clears the bot-protection token.
type switches the project’s platform. The new platform decides what identity the project needs:
switching to ios or android takes a bundleId, and switching to web takes a domain, so pass
the new one in the same call. The server refuses a switch the project’s use cases do not support on
the new platform. bundleId alone is checked against the project’s stored platform.
botProtectionToken is the token Binclusive appends to the user agent of the browsers it drives
on the project’s site, so a site behind bot protection can let its audits through. The server
refuses a value that is not a valid HTTP token.
egressCountry picks where the project’s cloud audits reach its site from: us leaves from
34.27.21.155, tr from 37.230.105.250. A project created without one audits from us. A site
that only lets in known addresses must allowlist the one its project uses. Pass egressCountry to
create_project instead when the first audit must already leave from that country.
Returns: { updateProject: { project } }, including the project’s type, bundleId,
egressCountry and botProtectionToken.
set_project_use_cases
Section titled “set_project_use_cases”Replace what the customer wants from a project.
| Name | Type | Required | Notes |
|---|---|---|---|
project_id | string | yes | |
use_cases | enum[] | yes | At least one of usability | ci | altText. Replaces the current set. |
The server refuses a use case the project’s platform does not support. See Vocabularies.
Returns: the project’s id, name and useCases.
configure_project_languages
Section titled “configure_project_languages”Turn audit languages on or off for a project. Requires the admin role.
| Name | Type | Required | Notes |
|---|---|---|---|
project_id | string | yes | |
enable | string[] | no | Locale codes to start auditing in, e.g. tr. |
disable | string[] | no | Locale codes to stop auditing in. |
Languages you name in neither list are left as they are. A code the product does not support, or one named in both lists, is refused naming it. The organization’s plan caps how many languages a project may have, the language its descriptions are written in included; a call that would go past it is refused. A project above its cap after a downgrade keeps its languages and may remove them, but not add.
Returns: the project’s id, name and config.languages, the full list now switched on.
configure_project_audit_schedule
Section titled “configure_project_audit_schedule”Set or turn off a project’s recurring cloud audit. Requires the admin role.
| Name | Type | Required | Notes |
|---|---|---|---|
project_id | string | yes | |
schedule | daily | weekly | monthly | no | Leave it out to turn the schedule off. |
Each scheduled audit is a cloud run, and it counts against the organization’s cloud-run quota. See Vocabularies.
Returns: the project’s id, name and config with its auditSchedule and
auditScheduleLastDispatch.
get_project_widget_settings
Section titled “get_project_widget_settings”Get a project’s accessibility widget settings.
| Name | Type | Required |
|---|---|---|
project_id | string | yes |
Returns: { widget }, the project’s config.widget: the same settings the dashboard’s widget
settings page reads, under the names configure_project_widget takes. A setting nobody has changed
may be absent.
configure_project_widget
Section titled “configure_project_widget”Change a project’s accessibility widget settings. Requires the admin role and a plan that includes the widget.
| Name | Type | Required | Notes |
|---|---|---|---|
project_id | string | yes | |
widget | object | yes | The settings to change. Every field is optional. |
widget takes these fields. A field you leave out keeps its value, and null clears it.
| Field | Type | Notes |
|---|---|---|
position, mobilePosition | top-left | top-right | center-left | center-right | bottom-left | bottom-right | Where the trigger sits, on a desktop and on a phone. |
xOffset, yOffset, mobileXOffset, mobileYOffset | integer | Offset of the trigger from its anchor, in pixels. |
triggerWidth, triggerHeight, mobileTriggerWidth, mobileTriggerHeight | integer | Size of the trigger, in pixels. |
triggerShape | circle | square | |
primaryColor, triggerColor, triggerSecondaryColor, backgroundColor, foregroundColor, accentColor | string | Hex colours, #rgb or #rrggbb, e.g. #1a73e8. |
fontFamily, fontUrl | string | The panel’s font. An uploaded font must belong to this organization. |
customerName, customerLogoUrl | string | The name and logo the panel shows. |
allowHideForever, whitelabel, fixWithAI | boolean | Whether a visitor may hide the widget for good, whether the Binclusive brand is hidden, and whether Fix with AI is offered. |
actionOverrides | { action, enabled }[] | Actions to turn on or off, e.g. { "action": "fontSize", "enabled": false }. |
profileOverrides | { profile, enabled }[] | Profiles to turn on or off, e.g. { "profile": "focusMode", "enabled": true }. |
The tool’s argument schema lists every action and profile it accepts.
A caller without the admin role, an organization whose plan has no widget, a fixWithAI of true
on a plan without it, a colour that is not hex, a font URL that is not a full https address on an
allowed host, and a font URL another organization uploaded are each refused with nothing saved, and
the tool returns an error block with the server’s message.
Returns: the project’s id, name and config.widget, the settings now in force.
delete_project
Section titled “delete_project”Delete a project. Requires the admin role.
| Name | Type | Required |
|---|---|---|
project_id | string | yes |
Returns: the confirmation line Deleted project: <name>.
import_sitemap
Section titled “import_sitemap”Import pages from a sitemap URL into a project.
| Name | Type | Required | Notes |
|---|---|---|---|
project_id | string | yes | |
sitemap_url | string | yes | URL of the sitemap to import. |
The crawl is asynchronous. The tool returns as soon as it is queued:
Sitemap crawl started. Check the project's sitemap diff panel for results. — the imported pages
appear in the dashboard’s sitemap diff panel, not in this response.
If the crawl is refused, the tool returns Failed to start sitemap crawl. without marking the
result as an error, so check the text rather than assuming success.
To re-import the sitemap on a schedule instead of once, use
configure_project_sitemap.
list_personas
Section titled “list_personas”List a project’s personas: the test accounts its journeys sign in as.
| Name | Type | Required |
|---|---|---|
project_id | string | yes |
Returns: { personas }. Each persona carries its id, name and logins, one per deployment
that has a captured login. A login carries deploymentId, deploymentName, capturedAt and
health: unverified until a run replays it, healthy once a run got past the login wall,
expired once a run hit one.
A persona id is what persona_id takes on create_journey, update_journey,
import_qa_journeys and set_qa_journey_persona.
A deployment missing from a persona’s logins has no login captured for it, and a run there of a
journey with that persona is refused. MCP captures no login, because capture needs a local
browser: the person runs b8e profile create --persona … --target … on their own machine.
Returns an error block if the project is not found.
create_persona
Section titled “create_persona”Create a persona in a project. It starts with no login.
| Name | Type | Required | Notes |
|---|---|---|---|
project_id | string | yes | |
name | string | yes | e.g. Pro user. |
test_account_acknowledged | true | yes | You confirm the persona logs in as a dedicated test account. A run that signs in as it stores that account’s screenshots and page text. |
A call without test_account_acknowledged: true is refused before anything is written. Capture the
persona’s login afterwards with b8e profile create --persona … --target ….
Returns: { personaId }. A name the server refuses, such as one the project already uses,
returns an error block with the server’s message.
delete_persona
Section titled “delete_persona”Delete a persona.
| Name | Type | Required |
|---|---|---|
persona_id | string | yes |
Returns: the confirmation line Deleted persona: <persona id>.
A persona a journey still signs in as is not deleted. The tool returns an error block holding
{ refused: "AuthPersonaInUse", personaId, journeyCount, message }, where journeyCount is the
number of journeys that use it. Point those journeys at another persona, or none, and delete again.