CodeSampleX

REST · CLI · MCP · SKILL.MD

기능

설치 없이 URL 요청만으로 네트워크를 읽습니다. 이 머신에서 실제로 무슨 일이 일어나는지 CodeSampleX가 관측하고 검증하게 하려면 CLI를 설치하세요. 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로 답합니다. 이것도 진짜 답입니다. 네트워크가 그 경우를 위해 만들고 실행한 것이 없다는 뜻입니다. match보다 different[]를 먼저 읽으세요. 비슷한 환경을 정확한 환경으로 승격하지 않습니다.

읽기 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 바이너리 그 자체라서 csx가 설치되지 않은 MCP 클라이언트에는 대화할 서버가 없습니다.

기능 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 도구는 의도적으로 제공하지 않습니다.

증거 찾기와 확인

공개 소프트웨어와 심벌에 대해 검증된 답을 찾고, 파일을 받거나 호환성 증거를 확인합니다.

search_known_solution 설명한 환경을 기준으로 등급이 매겨진 검증 해법을 찾습니다.

하는 일

로컬 CodeSampleX 네트워크 캐시를 검색합니다. 답이 있으면 일치 등급, 환경 차이, 필요한 수정, 증거 수와 실제 통과한 계약을 보여줍니다. 답이 없으면 추측하지 않고 NO_SAFE_MATCH를 반환합니다.

사용할 때

공개 라이브러리·SDK·런타임·OS 명령·독립 CLI를 쓰기 전이나, 이미 검증된 오류 우회법이 있을 법할 때 호출합니다.

입력

필수

query string
하려는 일이나 고치려는 문제를 평문으로 적습니다.

선택

packages string[]
공개 대상 좌표입니다. 레지스트리 패키지는 pkg:npm/axios@1.12.0, npm CLI 자체는 pkg:generic/cli/npm@11.5.2처럼 적습니다.
symbols string[]
axios.post 같은 공개 심벌 계열입니다.
environment object
희소한 환경 지문입니다. 생태계, OS, 아키텍처, 런타임, 언어, 컴파일러, 패키지 관리자, 모듈 시스템, 프레임워크, 실행 컨텍스트, 브라우저/엔진, libc, 가상화, 컨테이너 런타임 등을 알 때만 넣습니다.
errorText string
로컬에서 오류 코드와 지문으로 정제할 원본 오류 문구입니다.

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 텍스트와 검색 응답이 든 structuredContent를 반환합니다. 사용할 수 있는 답에는 로컬 offerId가 붙고, 미스에는 packageOverview와 localReady가 포함될 수 있습니다.

{
  "structuredContent": {
    "schemaVersion": 2,
    "results": [{"grade":"EXACT","sampleId":"sha256:..."}],
    "offerId": "local-offer-id"
  }
}
get_sample 캐시된 공개 샘플 하나의 매니페스트와 읽을 수 있는 파일을 가져옵니다.

하는 일

샘플 매니페스트와 캐시된 텍스트 파일을 반환합니다. 파일 하나는 64KB로 제한하고 바이너리는 건너뜁니다. 공개 샘플은 MIT-0 커뮤니티 아티팩트입니다.

사용할 때

search_known_solution이 sampleId를 반환했고 실행 가능한 전체 예제가 필요할 때 사용합니다.

입력

필수

sampleId string
sha256:... 형식의 콘텐츠 주소 샘플 ID입니다.

선택

입력 필드가 없습니다.

JSON 입력 예시

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

출력 형식과 예시

MCP 텍스트와 sampleId, manifest, 경로별 내용이 든 files 객체를 structuredContent로 반환합니다.

{
  "structuredContent": {
    "sampleId": "sha256:...",
    "manifest": {"license":"MIT-0","packages":["pkg:npm/axios@1.12.0"]},
    "files": {"src/index.mjs":"..."}
  }
}
explain_compatibility 패키지와 선택한 심벌의 캐시된 호환성 증거를 설명합니다.

하는 일

로컬 호환성 샤드를 읽고, 성격이 다른 프로젝트 관측과 계약 검증 증거를 합산하지 않고 따로 보여줍니다.

사용할 때

결과 뒤의 심벌별 증거가 필요하거나 패키지 하나를 목표 환경과 비교할 때 사용합니다.

입력

필수

package string
pkg:npm/axios@1.12.0 같은 패키지 purl입니다.

선택

symbol string
axios.post 같은 공개 심벌 계열입니다.
environment object
search_known_solution이 받는 것과 같은 희소 환경 지문입니다.

JSON 입력 예시

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

출력 형식과 예시

MCP 텍스트와 package, symbol, 기초 호환성 snapshot(없으면 null)이 든 structuredContent를 반환합니다.

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

실행하며 관측하기

평소처럼 빌드나 테스트를 실행하면서 공개 패키지의 정제된 결과를 기록합니다.

run_observed_command argv 명령을 증거 순환 안에서 실행하고 실제 종료 코드를 반환합니다.

하는 일

공개 의존성을 살피고 명령을 로컬에서 실행한 뒤 단계와 결과를 분류해, 원래 종료 코드와 정제된 오류 템플릿만 반환합니다.

사용할 때

패키지 의존 코드를 채택하거나 만든 뒤 빌드와 테스트를 CodeSampleX 밖에서 직접 실행하는 대신 사용합니다.

입력

필수

command string[]
["npm","test"] 같은 명령 argv입니다.

선택

cwd string
작업 디렉터리이며 생략하면 현재 디렉터리입니다.

JSON 입력 예시

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

출력 형식과 예시

MCP 텍스트와 exitCode, stage, result, sanitizedErrors, evidenceClass가 든 structuredContent를 반환합니다.

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

증거 순환 완성하기

제공된 답이 실제로 통했는지 알리거나, 답을 못 찾은 뒤 클린룸 샘플 제안을 준비합니다.

report_sample_adoption 검색 결과를 적용했는지와 다음 빌드가 통과했는지 기록합니다.

하는 일

보고를 search_known_solution이 반환한 로컬 제안과 연결해 ADOPTION_EVIDENCE로 기록합니다. 전체 로컬 상관관계가 증명될 때만 실패를 피한 것으로 셉니다.

사용할 때

제공된 샘플을 쓸지 결정하고 적용 뒤 빌드 결과를 알게 됐거나 알 수 없음이 확정됐을 때 호출합니다.

입력

필수

offerId string
search_known_solution이 반환한 불투명한 로컬 제안 ID입니다.
sampleId string
제공된 sha256 콘텐츠 주소입니다.
applied boolean
샘플의 접근법을 적용했는지 여부입니다.

선택

buildPass boolean
적용 뒤 프로젝트가 빌드 또는 테스트를 통과했는지 여부이며, 모르면 생략합니다.

JSON 입력 예시

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

출력 형식과 예시

MCP 텍스트와 recorded, uploadQueued, sampleId, applied, reportedFailureAvoided, evidenceClass 및 제공된 경우 buildPass가 든 structuredContent를 반환합니다.

{
  "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 정제된 클린룸 작업 지시서와 scaffold가 갖춰진 로컬 작업공간을 만듭니다.

하는 일

목표, 공개 패키지 purl, 공개 심벌로 제안을 만들고, 생성 지침과 함께 spec.json·PROMPT.md·csx.json manifest scaffold가 이미 들어 있는 작업공간 경로를 반환합니다. 작업공간을 만들지 못하면 경로를 반환하지 않고 실패합니다. 이 도구는 게시할 수 없습니다.

사용할 때

NO_SAFE_MATCH 뒤에 문제 경계를 해결했고 관측 빌드나 계약이 통과했을 때 사용합니다.

입력

필수

goal string
샘플이 증명해야 할 동작입니다.
packages string[]
샘플이 반드시 사용할 공개 패키지 purl입니다.

선택

symbols string[]
샘플이 보여줘야 할 공개 심벌 계열입니다.

JSON 입력 예시

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

출력 형식과 예시

MCP 텍스트와 spec, prompt, workdir, publishRequiresUserApproval이 든 structuredContent를 반환합니다.

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

이 설치 상태 확인하기

아무것도 업로드하지 않고 최근 로컬 검색 결과와 로컬 통계를 확인합니다.

list_local_hits 로컬에 저장된 최근 검색 적중, 등급, 적용 결과를 나열합니다.

하는 일

최근 적중의 시각, 질의, 등급, 샘플 ID, 적용 상태와 보고된 경우 적용 후 빌드 결과를 반환합니다.

사용할 때

이 설치본이 어떤 답을 받았고 나중에 적용했는지 확인할 때 사용합니다.

입력

필수

입력 필드가 없습니다.

선택

입력 필드가 없습니다.

JSON 입력 예시

{}

출력 형식과 예시

MCP 텍스트와 hits 배열이 든 structuredContent를 반환합니다. postBuildPass는 모르면 생략됩니다.

{
  "structuredContent": {
    "hits": [{"ts":"2026-08-13T10:00:00Z","query":"axios post","grade":"COMPATIBLE","sampleId":"sha256:...","adopted":true,"postBuildPass":true}]
  }
}
get_local_stats 이 설치본의 모드, 캐시, 대기열, 적중, 적용 통계를 읽습니다.

하는 일

현재 로컬 통계 객체를 반환합니다. 흔한 키로 mode, hits, cachedSamples, queuedUploads, pendingObservations와 검증된 우회 결과 통계가 있으며 항목은 늘어날 수 있습니다.

사용할 때

초기화, 캐시 준비 상태, 대기 중인 커뮤니티 작업, 증거 순환이 반복 사용되는지를 확인할 때 사용합니다.

입력

필수

입력 필드가 없습니다.

선택

입력 필드가 없습니다.

JSON 입력 예시

{}

출력 형식과 예시

MCP 텍스트와 로컬 통계 맵을 structuredContent로 바로 반환합니다.

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

URL만 가져올 수 있는 에이전트를 위해

이 표면의 기계 판독용 안내서입니다. 네트워크가 무엇에 답하는지, 언제 물을지, 엔드포인트 순서, 등급의 의미, 환경 불일치 처리 규칙, 선택적 실행 족적을 남기는 법을 담습니다. HTTPS 외에는 아무것도 요구하지 않습니다.

https://codesamplex.dev/skill.md