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를 쓰기 전이나, 이미 검증된 오류 우회법이 있을 법할 때 호출합니다.
입력
필수
querystring- 하려는 일이나 고치려는 문제를 평문으로 적습니다.
선택
packagesstring[]- 공개 대상 좌표입니다. 레지스트리 패키지는 pkg:npm/axios@1.12.0, npm CLI 자체는 pkg:generic/cli/npm@11.5.2처럼 적습니다.
symbolsstring[]- axios.post 같은 공개 심벌 계열입니다.
environmentobject- 희소한 환경 지문입니다. 생태계, OS, 아키텍처, 런타임, 언어, 컴파일러, 패키지 관리자, 모듈 시스템, 프레임워크, 실행 컨텍스트, 브라우저/엔진, libc, 가상화, 컨테이너 런타임 등을 알 때만 넣습니다.
errorTextstring- 로컬에서 오류 코드와 지문으로 정제할 원본 오류 문구입니다.
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를 반환했고 실행 가능한 전체 예제가 필요할 때 사용합니다.
입력
필수
sampleIdstring- 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
패키지와 선택한 심벌의 캐시된 호환성 증거를 설명합니다.
하는 일
로컬 호환성 샤드를 읽고, 성격이 다른 프로젝트 관측과 계약 검증 증거를 합산하지 않고 따로 보여줍니다.
사용할 때
결과 뒤의 심벌별 증거가 필요하거나 패키지 하나를 목표 환경과 비교할 때 사용합니다.
입력
필수
packagestring- pkg:npm/axios@1.12.0 같은 패키지 purl입니다.
선택
symbolstring- axios.post 같은 공개 심벌 계열입니다.
environmentobject- 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 밖에서 직접 실행하는 대신 사용합니다.
입력
필수
commandstring[]- ["npm","test"] 같은 명령 argv입니다.
선택
cwdstring- 작업 디렉터리이며 생략하면 현재 디렉터리입니다.
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로 기록합니다. 전체 로컬 상관관계가 증명될 때만 실패를 피한 것으로 셉니다.
사용할 때
제공된 샘플을 쓸지 결정하고 적용 뒤 빌드 결과를 알게 됐거나 알 수 없음이 확정됐을 때 호출합니다.
입력
필수
offerIdstring- search_known_solution이 반환한 불투명한 로컬 제안 ID입니다.
sampleIdstring- 제공된 sha256 콘텐츠 주소입니다.
appliedboolean- 샘플의 접근법을 적용했는지 여부입니다.
선택
buildPassboolean- 적용 뒤 프로젝트가 빌드 또는 테스트를 통과했는지 여부이며, 모르면 생략합니다.
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.
입력
필수
anomalyTypestring- Which kind of mismatch this is.
packagestring- The exact public coordinate the mismatch is about.
csxObservedobject- What CSX actually concluded.
localObservedobject- What was measured locally; result must be PASS or FAIL.
선택
symbolstring- Symbol family involved.
environmentobject- Sparse environment fingerprint.
sampleIdstring- The sample the contested answer came from — what makes it reproducible.
evidenceIdstring- The evidence id the contested answer came from.
reproduciblestring- yes | no | unknown, as measured.
confidencestring- low | medium | high. Ranking only, never truth.
errorTextstring- Raw local error output. Sanitized on this machine and never forwarded raw.
relatedIdsstring[]- Related sample, evidence or dependency ids.
llmHypothesisstring- 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.
입력
필수
affectedSurfacestring- Which surface this is about.
issueKindstring- Which kind of defect this is.
componentstring- The tool or endpoint, e.g. search_known_solution.
actualBehaviorstring- What actually happened, in one short sanitized sentence.
expectedBehaviorstring- What should have happened. It must differ from actualBehavior.
선택
requestFingerprintstring- A stable non-identifying request id — what makes two occurrences one report.
publicInputobject- The public part of the input that triggered it.
reproduciblestring- yes | no | unknown, as measured.
confidencestring- low | medium | high. Priority hint only, never truth.
relatedIdsstring[]- Related stable ids: sample, evidence, dependency, finding.
llmHypothesisstring- 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 뒤에 문제 경계를 해결했고 관측 빌드나 계약이 통과했을 때 사용합니다.
입력
필수
goalstring- 샘플이 증명해야 할 동작입니다.
packagesstring[]- 샘플이 반드시 사용할 공개 패키지 purl입니다.
선택
symbolsstring[]- 샘플이 보여줘야 할 공개 심벌 계열입니다.
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 외에는 아무것도 요구하지 않습니다.