# 1cent Web Intelligence for AI Agents

[![Quality](https://github.com/maxzoa/1cent/actions/workflows/quality.yml/badge.svg)](https://github.com/maxzoa/1cent/actions/workflows/quality.yml)
[![External health](https://github.com/maxzoa/1cent/actions/workflows/external-health.yml/badge.svg)](https://github.com/maxzoa/1cent/actions/workflows/external-health.yml)
[![Glama connector](https://img.shields.io/badge/Glama-Healthy%20connector-19c37d)](https://glama.ai/mcp/connectors/ru.maxzoa/1cent)
[![Smithery](https://smithery.ai/badge/maxzoa27/onecent)](https://smithery.ai/servers/maxzoa27/onecent)
[![LobeHub](https://img.shields.io/badge/LobeHub-Listed-2f80ed)](https://lobehub.com/mcp/maxzoa-1cent)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-ru.maxzoa%2F1cent-5c4ee5)](https://registry.modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

Give AI agents safe, bounded web intelligence without subscriptions, API keys or handing a crawler
unrestricted network access. Start with three free MCP tools; pay only for the URL operation used.
Production uses x402 v2, Base Mainnet USDC and PayAI.

Try the real safe fetch path in one command — fixed `example.com`, no payment:

```bash
curl -sS https://1cent.maxzoa.ru/v1/demo/live-pulse
```

Or preview one URL of your choice without payment, limited to one preview per client and UTC day:

```bash
curl -sS "https://1cent.maxzoa.ru/v1/demo/preview?url=https%3A%2F%2Fexample.com%2F"
```

- MCP: `https://1cent.maxzoa.ru/mcp`
- Free product demo: `https://1cent.maxzoa.ru/v1/demo/pulse`
- Free live demo: `https://1cent.maxzoa.ru/v1/demo/live-pulse`
- Live catalog/prices: `https://1cent.maxzoa.ru/v1/catalog`
- Public trust status: `https://1cent.maxzoa.ru/status.json`
- Buyer guide: `https://1cent.maxzoa.ru/docs/getting-started`
- Browser purchase entry: `https://1cent.maxzoa.ru/try`
- Outcome packages: `https://1cent.maxzoa.ru/v1/products`

Release 0.8.1 exposes 43 paid REST/MCP operations plus three free MCP tools:

- `catalog.tools.search` — find the correct operation and live price without a URL fetch;
- `demo.url.pulse` — inspect a fixed precomputed output sample without payment or network access.
- `demo.live.pulse` — run the real safe service against fixed `example.com`, rate-limited.

Public MCP discovery uses navigable dot-notation (`web.url.status`, `web.site.openapi`,
`web.batch.url_status`). Pre-0.6
underscore names remain accepted as compatibility aliases but are intentionally omitted from
`tools/list`.

MCP also publishes one buyer prompt (`choose_url_tool`) and one static buyer-guide resource
(`onecent://buyer-guide`). Every input field includes constraints, examples and machine-readable
descriptions so agents can choose and call tools correctly on the first attempt.

## Find 1cent

- Official MCP Registry: `ru.maxzoa/1cent`;
- Glama remote connector: `https://glama.ai/mcp/connectors/ru.maxzoa/1cent`;
- Smithery: `https://smithery.ai/servers/maxzoa27/onecent`;
- MCP.so: `https://mcp.so/servers/1cent`;
- LobeHub: `https://lobehub.com/mcp/maxzoa-1cent`.
- MCPServers.org: `https://mcpservers.org/ru/servers/maxzoa/1cent`.

Glama release verification uses the repository's `onecent-glama` stdio entry point. It loads the
same MCP tool registry as production for schema inspection; it does not provide a payment bypass
or a second implementation of paid URL operations.

Directory status is checked with dated evidence in
[Marketplace quality report](MARKETPLACE_QUALITY_062_REPORT.md). A page returning HTTP 200 alone is
not counted as a successful listing: it must be searchable, current and installable.

Buyer setup starts with a no-payment diagnostic:

```bash
onecent doctor
```

Generate or install a secret-free MCP client configuration:

```bash
onecent install --client claude
onecent install --client cursor --apply
onecent install --client vscode --apply
onecent install --client codex
```

For MCP clients without native x402 signing, install the local Buyer Bridge:

```bash
pipx install "onecent[buyer]==0.8.1"
onecent wallet set
onecent bridge
```

Manual one-call approval is the default and has no commercial daily quota. The OS keyring holds
the buyer secret; 1cent, remote MCP
and catalog services never receive it. UNKNOWN outcomes are never retried. See
[Buyer Bridge](BUYER_BRIDGE.md) for Claude, Cursor, VS Code and Codex setup.

The direct CLI also refuses a paid call unless the buyer explicitly supplies a maximum amount,
confirms Base Mainnet and types the one-call confirmation. See `examples/buyer-python` and
`examples/buyer-node`.

Node buyers can install the public release package:

```bash
npm install --global onecent-buyer@0.8.1
onecent-buyer doctor
```

The package source remains available in [`packages/onecent-buyer`](packages/onecent-buyer).
Registry pages: [PyPI `onecent` 0.8.1](https://pypi.org/project/onecent/0.8.1/) and
[npm `onecent-buyer` 0.8.1](https://www.npmjs.com/package/onecent-buyer/v/0.8.1).

The bounded batch tool accepts one to five distinct public URLs. Its x402 quote is the live
unit price multiplied by the validated URL count before any URL fetch begins. Results retain
input order and use an explicit partial-failure contract; UNKNOWN payments are never retried.

The product denominator, including planned, externally blocked and unsafe outcomes, is published
in [WEB_INTELLIGENCE_COVERAGE_MATRIX.md](WEB_INTELLIGENCE_COVERAGE_MATRIX.md) with JSON and CSV.

`onecent watch` provides finite, capped change monitoring. It is disabled by default, requires
explicit Base network/asset/seller confirmations and stops on UNKNOWN without creating a new
payment attempt.

PostgreSQL is the runtime source for tool availability and atomic Base USDC prices. Config
values are clean-install fallbacks. Paid URL work begins only after successful payment checks.

## Safety contract

- public HTTP/HTTPS only; private, loopback, link-local and rebinding destinations fail closed;
- strict input schemas; unknown fields rejected;
- bounded redirects, response bodies, extracted text, concurrency and queue depth;
- payment identifier, request fingerprint and idempotent replay protection;
- UNKNOWN settlement never retried automatically;
- no seller private key, buyer key, Docker socket or JavaScript execution on the server;
- Streamable HTTP host/origin protection enabled for remote MCP.
- optional signed x402 offers and settlement receipts use a dedicated Ed25519 `did:web` key;
  they never expose or reuse a buyer or seller private key.

## Local quality checks

```bash
python -m venv .venv
.venv/Scripts/pip install --require-hashes -r requirements-dev.lock
.venv/Scripts/pip install --no-deps -e .
ruff check .
mypy
pytest -q
python scripts/validate_release.py
docker compose --env-file .env.example config
docker compose --env-file .env.example build
pip-audit --no-deps -r requirements.lock --progress-spinner off
```

## Local Docker start

Copy `.env.example` to `.env`, replace placeholders, keep `X402_ENVIRONMENT=testnet` and
`X402_NETWORK=eip155:84532`, then:

```bash
docker compose up -d --build
docker compose ps
```

Container UID/GID: `10001:10001`. No host bind-mounted writable directory is required.
This local example is intentionally testnet. Production mainnet activation requires owner approval,
a fresh PostgreSQL backup, production preflight, development bypass disabled and rollback readiness.

## Documentation

- [Current production state](CURRENT_PRODUCTION.md)
- [Documentation map](DOCS_INDEX.md)
- [Public REST API](API.md)
- [Remote MCP server](MCP.md)
- [Buyer quickstart](BUYER_QUICKSTART.md)
- [Local MCP Buyer Bridge](BUYER_BRIDGE.md)
- [Security policy](SECURITY.md)
- [Release history](CHANGELOG.md)
- [Marketplace quality report](MARKETPLACE_QUALITY_062_REPORT.md)
- [Scaling and trust gates](TRUST_AND_SCALING_READINESS.md)
- [Production operations](MAINNET_RUNBOOK.md)
- [Incident response](INCIDENT_RESPONSE.md)

Licensed under Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).