REST · CLI · MCP · SKILL.MD

Возможности

Читайте сеть обычным запросом по URL, ничего не устанавливая. Установите CLI, когда хотите, чтобы CodeSampleX наблюдал и проверял, что на самом деле происходит на вашей машине. MCP — адаптер поверх CLI.

REST

Чтобы читать сеть, ничего устанавливать не нужно

Каждый ответ, который показывает этот сайт, доступен одним обычным HTTPS-запросом: без ключа, без аккаунта, без клиентской библиотеки. Страница в браузере, скрипт, задача CI или инструмент fetch облачного агента получают тот же оценённый ответ, что и CLI. Маршруты открыты для любого origin.

Один запрос, настоящий JSON — скопируйте как есть:

curl 'https://codesamplex.dev/v2/search?package=pkg:npm/axios&symbol=axios.post&os=linux&runtime=node&runtimeVersion=22'

Если ничего нет, ответ — grade NO_SAFE_MATCH. Это настоящий ответ: в сети нет ничего собранного и запущенного для этого случая. Читайте different[] раньше match — близкое окружение никогда не повышается до точного.

API для чтения

Всё, что показывает этот сайт, отдаётся этими маршрутами, и они отвечают без ключа. Пишущая половина — пакеты свидетельств, публикация образца, получение работы по проверке — требует личности сидера или токена воркера и относится к CLI. Маршруты не переводятся по той же причине, что и находки: пути и имена полей и есть сам предмет.

Предоставляемые свидетельства (Evidence) и агрегированные данные о совместимости доступны по лицензии CDLA-Permissive-2.0. Публикуемые образцы по умолчанию распространяются под MIT-0. См. DATA_TERMS.md.

GET	/v2/search?q=&package=&symbol=&os=&runtime=&runtimeVersion=	Search the network from a URL: packages, symbols, error codes, graded against the environment you name. The same pipeline the MCP tool and the CLI run; a miss is spelled grade=NO_SAFE_MATCH.
POST	/v2/search	The same search as a JSON body: {schemaVersion:2, query, packages[], symbols[], environment{}}. Each result carries sampleUrl, exact[], different[] and adaptationNeeded[].
POST	/v1/search	The frozen v1 response shape, for clients that pinned it.
GET	/v1/registry/packages/{purl}	One package's compatibility snapshot, by PURL. Percent-encode the slash: pkg:npm%2Faxios@1.12.0.
GET	/v1/registry/symbols/{ecosystem}/{name}/{symbol}	One API's snapshot: where it ran, where it failed, at what evidence level.
GET	/v1/samples/{sampleId}	A published sample's manifest: its case, its contract, its verification receipts.
GET	/v1/samples/{sampleId}/artifact	That sample's files. The id is the hash of the contents, so the bytes verify themselves.
GET	/findings.json?eco=&os=&runtime=&q=&basis=	Every finding the /findings page shows, as one document: what was believed, what was measured, and the sample that proves it.
GET	/v1/wanted	What the network has been asked for and has no sample for yet.
GET	/v1/adapters	The ecosystems and lockfiles the scanner reads, and which ecosystems verify.
GET	/v1/stats	Observation, sample and package counts — what the front page's tiles are drawn from.
GET	/v1/shards/{ecosystem}/{name}/{n}	The offline shard a client syncs, so a machine can answer without asking again. ETag-cached.
GET	/v1/peers/for-sample/{sampleId}	Peers holding that sample, for fetching it without this server.
POST	/v1/footprints/execution	The one write a zero-install caller may make: {sampleId, outcome: pass\|fail\|could_not_run, stage, environment{os,arch,runtime,runtimeVersion}}. Recorded as an unsigned self-report that weighs nothing in any grade.
GET	/skill.md	This surface as a machine-readable guide for an agent that can fetch a URL and nothing else.
GET	/version	Which build of the server answered, and in which environment.

Что умеет каждая дверь

REST, MCP и установленный CLI рядом. Каждая отметка сверяется с маршрутизатором и списком команд, и README несут те же отметки. MCP-сервер — это сам бинарник csx, поэтому у MCP-клиента без установленного csx нет сервера, с которым можно говорить.

Возможность	Web REST (без установки)	MCP	CLI установлен
Search verified samples, graded against an environment	yes	yes	yes
Compatibility lookup by package, version, symbol and environment	yes	yes	partial csx search grades against the synced shards; there is no explain command
Read one sample's manifest, receipts and files	yes	yes	partial through csx search --json; no dedicated sample read command
Read the findings collection	yes	no web and REST only	no web and REST only
Read gaps, wanted and public stats	yes	no	partial csx stats shows local counters only
Use from a browser, a cloud agent or a script	yes	partial the agent's MCP host must run csx locally	no a local binary
Zero-install use	yes	partial the MCP server is the csx binary; the client host must have csx installed	no
Detect the local project and environment automatically	no	partial only what the local csx behind the MCP host can see	yes
Run the real local build or test	no	partial run_observed_command runs it through the local csx	yes
Capture sanitized, structured execution evidence	no	partial only through the local csx the MCP host runs	yes
File an unsigned execution footprint	yes	no files correlated adoption evidence instead	no files correlated adoption evidence instead
Automatic failed-build lookup hook	no	no	yes
Background sync and offline cache	no	no	yes
Privacy preview before anything is uploaded	no	no	yes
Publish a verified sample	no	no deliberately no publish tool	yes a person confirms at the CLI
Worker and matrix verification	no	no	yes
Signed verification receipts (ed25519, from the worker)	no	no	yes

REST читает сеть. CLI позволяет сети наблюдать реальность.

Начните с CLI

Эти инструменты — способ, которым кодовый агент обращается к сети. CLI обращается к той же сети напрямую и перечисляет всё, что умеет.

csx helpкаждая команда — одна строка
csx worker --helpworker, update и mcp-config тоже принимают --help

MCP

MCP: адаптер поверх CLI

На этой странице описана вся публичная поверхность MCP. Инструмента MCP для публикации примеров намеренно нет.

Find and inspect evidence

Search for a verified answer, fetch its files, or inspect compatibility evidence for one public software target and symbol.

search_known_solution Find a verified solution graded against the environment you describe.

Что делает

Searches the local CodeSampleX network cache. A hit reports its match grade, environment differences, adaptations, evidence counts, and the contract assertions that actually passed. A miss is returned as NO_SAFE_MATCH, never guessed into a hit.

Когда использовать

Call before using a public library, SDK, runtime, OS command or standalone CLI, or when its error may already have a verified detour.

Входные данные

Обязательно

query string: What you are trying to do or fix, in plain words.

Необязательно

packages string[]: Public target coordinates: pkg:npm/axios@1.12.0 for a registry package or pkg:generic/cli/npm@11.5.2 for the npm CLI itself.
symbols string[]: Public symbol families, for example axios.post.
environment object: Sparse environment fingerprint; known values may include ecosystem, OS, architecture, runtime, language, compiler, package manager, module system, frameworks, execution context, browser/engine, libc, virtualization, and container runtime.
errorText string: Raw error text to sanitize locally into an error code and fingerprint.

Пример входного JSON

{
  "query": "send JSON and retry a reset connection",
  "packages": ["pkg:npm/axios@1.12.0"],
  "symbols": ["axios.post"],
  "environment": {"os":"linux","runtime":"node","runtimeVersion":"22.18","executionContext":"node"}
}

Форма и пример результата

MCP content text plus structuredContent containing the search response and a local offerId on an eligible hit. A miss can also include packageOverview and localReady.

{
  "structuredContent": {
    "schemaVersion": 2,
    "results": [{"grade":"EXACT","sampleId":"sha256:..."}],
    "offerId": "local-offer-id"
  }
}

get_sample Fetch the manifest and readable files for one cached public sample.

Что делает

Returns the sample manifest and cached text files. Each file is capped at 64 KB and binary files are skipped. Public samples are MIT-0 community artifacts.

Когда использовать

Use after search_known_solution returns a sampleId and you need the complete runnable example.

Входные данные

Обязательно

sampleId string: Content-addressed sample id in sha256:... form.

Необязательно

Полей нет.

Пример входного JSON

{"sampleId":"sha256:0123456789abcdef..."}

Форма и пример результата

MCP content text plus structuredContent with sampleId, manifest, and a path-to-content files object.

{
  "structuredContent": {
    "sampleId": "sha256:...",
    "manifest": {"license":"MIT-0","packages":["pkg:npm/axios@1.12.0"]},
    "files": {"src/index.mjs":"..."}
  }
}

explain_compatibility Explain cached compatibility evidence for a package and optional symbol.

Что делает

Reads local compatibility shards and keeps project observations separate from contract verification evidence instead of adding unlike evidence together.

Когда использовать

Use when you need the per-symbol evidence behind a result or want to compare one package with a target environment.

Входные данные

Обязательно

package string: Package purl, for example pkg:npm/axios@1.12.0.

Необязательно

symbol string: Public symbol family, for example axios.post.
environment object: The same sparse environment fingerprint accepted by search_known_solution.

Пример входного JSON

{
  "package": "pkg:npm/axios@1.12.0",
  "symbol": "axios.post",
  "environment": {"runtime":"node","runtimeVersion":"22.18"}
}

Форма и пример результата

MCP content text plus structuredContent with package, symbol, and the underlying compatibility snapshot (or null).

{
  "structuredContent": {
    "package": "pkg:npm/axios@1.12.0",
    "symbol": "axios.post",
    "snapshot": {"schemaVersion":1,"rows":[]}
  }
}

Run with observation

Execute a normal build or test while recording a sanitized public-package outcome.

run_observed_command Run an argv command through the evidence loop and return its real exit code.

Что делает

Scans public dependencies, runs the command locally, classifies its stage and result, and returns only sanitized error templates alongside the original exit code.

Когда использовать

Use for builds and tests after adopting or creating package-dependent code, instead of running the command outside CodeSampleX.

Входные данные

Обязательно

command string[]: Command argv, for example ["npm","test"].

Необязательно

cwd string: Working directory; defaults to the current directory.

Пример входного JSON

{"command":["npm","test"],"cwd":"project"}

Форма и пример результата

MCP content text plus structuredContent with exitCode, stage, result, sanitizedErrors, and evidenceClass.

{
  "structuredContent": {
    "exitCode": 0,
    "stage": "PROJECT_TEST",
    "result": "PASS",
    "sanitizedErrors": [],
    "evidenceClass": "USAGE_OBSERVATION"
  }
}

Close the evidence loop

Report whether an offered answer worked, or prepare a clean-room sample proposal after a miss.

report_sample_adoption Record whether a search result was applied and whether the next build passed.

Что делает

Correlates the report with the local offer returned by search_known_solution and records ADOPTION_EVIDENCE. A failure is counted as avoided only when the full local correlation proves it.

Когда использовать

Call after deciding whether to use an offered sample, once the post-adoption build result is known or explicitly unknown.

Входные данные

Обязательно

offerId string: Opaque local offer id returned by search_known_solution.
sampleId string: The offered sha256 content address.
applied boolean: Whether the sample approach was applied.

Необязательно

buildPass boolean: Whether the project built or passed after adoption; omit when unknown.

Пример входного JSON

{"offerId":"local-offer-id","sampleId":"sha256:...","applied":true,"buildPass":true}

Форма и пример результата

MCP content text plus structuredContent with recorded, uploadQueued, sampleId, applied, reportedFailureAvoided, evidenceClass, and buildPass when supplied.

{
  "structuredContent": {
    "recorded": true,
    "uploadQueued": true,
    "sampleId": "sha256:...",
    "applied": true,
    "buildPass": true,
    "reportedFailureAvoided": false,
    "evidenceClass": "ADOPTION_EVIDENCE"
  }
}

report_anomaly Submit a verification request when a CSX answer and your own local run concretely disagree.

Что делает

Files a CONCRETE, reproducible disagreement between what CodeSampleX returned and what was measured locally — a passing conclusion that fails on this machine, or a returned symbol signature the public package does not export. It is a verification request, not a finding: the report is queued for an independent re-run, and only a signed receipt can confirm it. Idempotent by fingerprint, so the same mismatch twice is one report.

Когда использовать

Use only with a measured local PASS or FAIL. "This looks wrong to me" is refused, and so is a NO_SAFE_MATCH with no reproducible public failure attached.

Входные данные

Обязательно

anomalyType string: Which kind of mismatch this is.
package string: The exact public coordinate the mismatch is about.
csxObserved object: What CSX actually concluded.
localObserved object: What was measured locally; result must be PASS or FAIL.

Необязательно

symbol string: Symbol family involved.
environment object: Sparse environment fingerprint.
sampleId string: The sample the contested answer came from — what makes it reproducible.
evidenceId string: The evidence id the contested answer came from.
reproducible string: yes | no | unknown, as measured.
confidence string: low | medium | high. Ranking only, never truth.
errorText string: Raw local error output. Sanitized on this machine and never forwarded raw.
relatedIds string[]: Related sample, evidence or dependency ids.
llmHypothesis string: A guess at the cause. Stored separately and excluded from the verdict.

Пример входного JSON

{"anomalyType":"CONTRACT_DISAGREES","package":"pkg:npm/axios@1.12.0","csxObserved":{"result":"PASS"},"localObserved":{"result":"FAIL"}}

Форма и пример результата

MCP content text plus structuredContent with the report id and its queued state.

{
  "structuredContent": {
    "reported": true,
    "queuedForVerification": true,
    "confirmed": false
  }
}

report_csx_issue Report a reproducible defect in CodeSampleX itself — the tools, server, site, verifier or farm.

Что делает

Files a defect in the product as distinct from its data: an answer that hid the failure you were looking at, a recommendation from an ecosystem the question never mentioned, a tool contract that made an agent behave wrongly, a response contract that breaks inconsistently on the same input. Idempotent by fingerprint: the same defect twice is one report with a higher occurrence count, never a second ticket.

Когда использовать

Use report_anomaly instead when the disagreement is about a PACKAGE rather than about this product. This one is opt-in: it creates no ticket, a person triages it, and a week with no reports is normal.

Входные данные

Обязательно

affectedSurface string: Which surface this is about.
issueKind string: Which kind of defect this is.
component string: The tool or endpoint, e.g. search_known_solution.
actualBehavior string: What actually happened, in one short sanitized sentence.
expectedBehavior string: What should have happened. It must differ from actualBehavior.

Необязательно

requestFingerprint string: A stable non-identifying request id — what makes two occurrences one report.
publicInput object: The public part of the input that triggered it.
reproducible string: yes | no | unknown, as measured.
confidence string: low | medium | high. Priority hint only, never truth.
relatedIds string[]: Related stable ids: sample, evidence, dependency, finding.
llmHypothesis string: A guess at the cause. Stored separately and excluded from the verdict.

Пример входного JSON

{"affectedSurface":"MCP_TOOL","issueKind":"WRONG_RESULT","component":"search_known_solution","actualBehavior":"returned a cargo sample for a go build","expectedBehavior":"NO_SAFE_MATCH"}

Форма и пример результата

MCP content text plus structuredContent with the report id and its occurrence count.

{
  "structuredContent": {
    "reported": true,
    "occurrences": 1,
    "ticketCreated": false
  }
}

propose_public_sample Create a sanitized clean-room brief and a scaffolded local workspace.

Что делает

Builds a proposal from a goal, public package purls, and public symbols, then returns generation instructions and a workspace path that already holds spec.json, PROMPT.md and a csx.json manifest scaffold. If it cannot create that workspace it fails instead of returning a path. This tool cannot publish.

Когда использовать

Use after NO_SAFE_MATCH when you solved the boundary and the observed build or contract passed.

Входные данные

Обязательно

goal string: The behavior the sample should prove.
packages string[]: Public package purls the sample must use.

Необязательно

symbols string[]: Public symbol families the sample should demonstrate.

Пример входного JSON

{"goal":"axios upload progress","packages":["pkg:npm/axios@1.12.0"],"symbols":["axios.post"]}

Форма и пример результата

MCP content text plus structuredContent with spec, prompt, workdir, and publishRequiresUserApproval.

{
  "structuredContent": {
    "spec": {"goal":"axios upload progress","packages":["pkg:npm/axios@1.12.0"]},
    "prompt": "Generate the sample...",
    "workdir": "<local clean-room path>",
    "publishRequiresUserApproval": true
  }
}

Inspect this installation

Read recent local search outcomes or the local dashboard counters without uploading anything.

list_local_hits List recent search hits, grades, and adoption outcomes stored locally.

Что делает

Returns recent hit rows with timestamp, query, grade, sample id, adopted state, and post-build result when it was reported.

Когда использовать

Use to audit which answers this installation received and whether they were later adopted.

Входные данные

Обязательно

Полей нет.

Необязательно

Полей нет.

Пример входного JSON

{}

Форма и пример результата

MCP content text plus structuredContent with a hits array. postBuildPass is omitted when unknown.

{
  "structuredContent": {
    "hits": [{"ts":"2026-08-13T10:00:00Z","query":"axios post","grade":"COMPATIBLE","sampleId":"sha256:...","adopted":true,"postBuildPass":true}]
  }
}

get_local_stats Read mode, cache, queue, hit, and adoption counters for this installation.

Что делает

Returns the current local stats object. Common keys include mode, hits, cachedSamples, queuedUploads, pendingObservations, and the verified-detour outcome counters; the available set can grow.

Когда использовать

Use to check initialization, cache readiness, pending community work, or whether the evidence loop is being used repeatedly.

Входные данные

Обязательно

Полей нет.

Необязательно

Полей нет.

Пример входного JSON

{}

Форма и пример результата

MCP content text plus the local stats map directly as structuredContent.

{
  "structuredContent": {
    "mode": "community",
    "hits": 7,
    "cachedSamples": 31,
    "queuedUploads": 0,
    "pendingObservations": 0
  }
}

Для агента, который умеет только получать URL

Машиночитаемое руководство по этой поверхности: что отвечает сеть, когда спрашивать, эндпоинты по порядку, что означает оценка, как обращаться с расхождением окружения и как оставить необязательный след выполнения. Оно не требует ничего, кроме HTTPS.

https://codesamplex.dev/skill.md