CodeSampleX MCP server
Commit Nov 15, 2026Provides real-world compatibility evidence for developer libraries, runtimes, and toolchains by recording actual build outcomes across diverse environments.
Also known as r2cuerdame/CodeSampleX
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.2.25
- Last commit
- Nov 15, 2026
- License
- Apache-2.0
What is CodeSampleX MCP?
CodeSampleX provides real-world compatibility evidence for developer libraries, runtimes, and toolchains by recording actual build outcomes across diverse environments.
Summary generated from the project's README
About CodeSampleX MCP server
CodeSampleX serves as an open compatibility testing network designed for developers who need to verify if specific libraries, runtimes, or toolchains function correctly in diverse environments. Unlike documentation summaries, this system records actual build outcomes and execution evidence from real machines, including macOS hosts, various ARM architectures, and specific musl or corporate base images. It provides developers with verified findings regarding where code works or breaks, filling gaps that container-based testing often misses.
Users can interact with the service through a public REST API for zero-install lookups or by installing the CLI to enable local execution capture and background synchronization. For those using AI agents, the tool can be run as an MCP server via the csx mcp command. The system distinguishes between community mode, which enables background sync, and local-only mode for restricted network access. It offers specific tools like csx search to find verified samples and csx run to record sanitized evidence from local builds.
What you can do with it
- 1Verify package compatibilityCheck if a specific npm package version works on a particular Linux runtime and OS combination.
- 2Automate build failure analysisUse a build-failure hook to automatically search for known compatibility issues when a shell build fails.
- 3Record local execution evidenceCapture and upload sanitized build outcomes from your own machine to contribute to the compatibility network.
- 4Identify environment gapsDetermine if there is a lack of verified testing data for your specific combination of runtime and architecture.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
CSX_REQUIRE_TEST_DSNCSX_TEST_DSN
| Name | Description | |
|---|---|---|
| CSX_REQUIRE_TEST_DSN | — | |
| CSX_TEST_DSN | — |
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabler2cuerdame/codesamplex is public and reachablegithub.com/r2cuerdame/codesamplex ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/r2cuerdame/codesamplex ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCodeSampleX
Tested. Not guessed.
Languages: English · 한국어 · 日本語 · 简体中文 · Español · Français · Deutsch · Português (BR) · Русский
Start here: CLI quick start · Use the public REST API without installing · Connect an MCP client
CLI quick start (Windows PowerShell)
Install, check the binary, then ask your first question in PowerShell:
irm https://codesamplex.dev/install.ps1 | iex
csx version
csx search "axios multipart upload" --package pkg:npm/axios
The installer asks you to choose JOIN COMMUNITY or LOCAL ONLY. Community mode warms the first cache and starts background sync; local-only mode disables automatic network access and may return no results from a cold cache. You can change modes later with csx init --community or csx init --local-only.
csx version prints csx v<version>. Search returns answers graded for the detected environment; read each result's environment differences before using it. NO_SAFE_MATCH means no verified match was found, not that installation failed. Run searches from your project directory to include its dependency and runtime context.
If PowerShell cannot find csx, open a new terminal or check the installed binary with & "$env:LOCALAPPDATA\csx\csx.exe" version. For macOS / Linux and installation details, or MCP client setup, continue below.
What CodeSampleX records
CodeSampleX is an open compatibility testing network for developer libraries, runtimes and toolchains. It does not summarize documentation and it does not collect anecdotes. It records what real builds actually did, in environments recorded rather than assumed — then shows you where things worked, where they broke, and in which environment.
Two things are the asset, and a third is a bonus:
- Evidence — real builds on real developer machines, with the environment, stage, structured termination, and secret-safe normalized failure fingerprint. Missing or legacy failure detail is shown as an Evidence gap, never invented as a cause. It arrives automatically wherever csx is installed, so it reaches platforms no container lane can: no container reproduces a macOS host — Docker on a Mac runs a Linux VM, which is a different machine wearing the same laptop — npm publishes no Windows image, and the long tail of musl, ARM, corporate base images and actually-installed runtime versions is unbounded. This is the only thing that can fill the map.
- Findings — the contradictions we detected in that evidence: what a competent developer or model expects, measured against what happened. These are ours to stand behind, and they are what a model most often gets wrong, because they are exactly what the documentation does not say.
- Samples — runnable code we write and verify ourselves. A bonus, deliberately: a container farm can never cover the space, so a verified sample is a confidence tier above the evidence, never the condition for having an answer at all.
Which is why a miss is not empty. When nothing has been proven for your case the grade stays NO_SAFE_MATCH — and the recorded observations come back with it, as recorded.
- Compatibility map: https://codesamplex.dev
- The question it answers: does it run there? — this API, on this version, on this OS, under this runtime.
- The answer it gives: here is what happened, and here is where it ran. Reporters use rotating peer buckets; separate first-party activity analytics use a stable pseudonymous client ID, never a name or IP identity. See analytics semantics.
What ships today
CodeSampleX is no longer just a search command. The shipped product now exposes several surfaces, all backed by the same evidence model:
| Surface | Current role |
|---|---|
| Compatibility | browse recorded compatibility by package, version, symbol and environment |
| Dependencies | reverse dependency atlas: which recorded parent releases pulled a dependency release; an edge is not a compatibility verdict |
| Gaps | completeness census across Sample / Evidence / Dependency, replacing the old website Wanted ranking |
| Findings | measured contradictions and version/environment boundaries backed by reproducible samples |
| Features | zero-install REST quick start, the REST / MCP / CLI capability matrix, the MCP tool contracts and skill.md |
| Samples · Adapters · Stats | verified artifacts, ecosystem capability matrix, and public network rollups |
The CLI is the canonical local interface. csx help is generated from the commands in the binary; this table is pinned to it by a test so a new command cannot silently outgrow the README.
| Command | What it does |
|---|---|
config |
read or change local settings |
daemon |
run, start, stop, or inspect the background sync daemon |
doctor |
diagnose the local install; --fix repairs safe CSX-owned state and verifies again |
hook |
enable, disable, inspect, or self-test the automatic build-failure lookup installed into supported coding agents |
init |
choose community/local-only mode, configure agents, warm the first cache, and start background sync |
login |
sign in with GitHub when you want attributed sample publishing |
mcp |
run the stdio MCP server used by agent clients |
mcp-config |
print JSON/TOML/path configuration for MCP clients |
run |
run a command and record sanitized evidence for public dependencies |
sample |
propose, create, preview, verify, publish, remove, list, or review pending clean-room samples |
sample-worker |
operate the private authoring work/session handoff lane |
scan |
detect public dependencies without running a build |
search |
search verified samples graded against the target environment |
stats |
show local cache, queue, hit, and adoption counters |
sync |
warm compatibility shards and flush queued community uploads (--uploads-only when needed) |
ui |
open the local dashboard and privacy preview |
update |
securely check, install, inspect, or roll back signed updates |
version |
print the installed csx version; --json adds revision, OS and arch for scripts |
worker |
contribute Docker-isolated cross/matrix verification work |
The network also installs an optional build-failure hook into supported coding agents. When an agent's shell build fails, the hook classifies the failing build step, sanitizes the error locally, searches CodeSampleX, and stays silent on a miss or unrelated command. csx hook status shows what is installed; csx hook check proves the registered hook path with a throwaway failing build.
No install needed to read the network
CodeSampleX exposes a public REST surface for agents, browsers and scripts. Every answer the site renders is a plain HTTPS request away — no key, no account, no client library, readable from any origin. Install the CLI only when you want local execution capture, the automatic failed-build hook, publishing or worker capabilities.
One request, real production JSON — copy it as it is:
curl 'https://codesamplex.dev/v2/search?package=pkg:npm/axios&symbol=axios.post&os=linux&runtime=node&runtimeVersion=22'
The answer carries a grade, and every result names which environment dimensions matched (exact[]) and which did not (different[]). A miss is spelled grade: "NO_SAFE_MATCH" — a real answer, not a failure to answer. A generic web-capable agent reads the whole contract from https://codesamplex.dev/skill.md; docs/rest.md is the same quick start for a person.
The three doors compared. Every mark is checked against the router and the command list by a test, and the Features page draws the same table:
| Capability | Web REST (no install) | MCP | CLI installed |
|---|---|---|---|
| Search verified samples, graded against an environment | ✅ | ✅ | ✅ |
| Compatibility lookup by package, version, symbol and environment | ✅ | ✅ | ⚠️ csx search grades against the synced shards; there is no explain command |
| Read one sample's manifest, receipts and files | ✅ | ✅ | ⚠️ through csx search --json; no dedicated sample read command |
| Read the findings collection | ✅ | ❌ web and REST only | ❌ web and REST only |
| Read gaps, wanted and public stats | ✅ | ❌ | ⚠️ csx stats shows local counters only |
| Use from a browser, a cloud agent or a script | ✅ | ⚠️ the agent's MCP host must run csx locally | ❌ a local binary |
| Zero-install use | ✅ | ⚠️ the MCP server is the csx binary; the client host must have csx installed | ❌ |
| Detect the local project and environment automatically | ❌ | ⚠️ only what the local csx behind the MCP host can see | ✅ |
| Run the real local build or test | ❌ | ⚠️ run_observed_command runs it through the local csx | ✅ |
| Capture sanitized, structured execution evidence | ❌ | ⚠️ only through the local csx the MCP host runs | ✅ |
| File an unsigned execution footprint | ✅ | ❌ files correlated adoption evidence instead | ❌ files correlated adoption evidence instead |
| Automatic failed-build lookup hook | ❌ | ❌ | ✅ |
| Background sync and offline cache | ❌ | ❌ | ✅ |
| Privacy preview before anything is uploaded | ❌ | ❌ | ✅ |
| Publish a verified sample | ❌ | ❌ deliberately no publish tool | ✅ a person confirms at the CLI |
| Worker and matrix verification | ❌ | ❌ | ✅ |
| Signed verification receipts (ed25519, from the worker) | ❌ | ❌ | ✅ |
REST reads the network. The CLI lets the network observe reality. MCP is an adapter on the CLI: csx mcp is the csx binary itself, so an MCP client on a host without csx has no server to talk to.
Does it run there?
Every result is tied to the environment that produced it, so the same data can be pivoted into version × symbol, OS × runtime, version × architecture, browser/runtime, libc, and other recorded dimensions. Use the live compatibility explorer or a package page such as pgx/v5 for current counts; the README deliberately does not freeze live network numbers into a dated screenshot. The shape below is illustrative only:
v5.10.0 v5.9.2
github.com/jackc/pgx/v5 ▤ — —
Batch ▤ — —
A matrix cell carries observations and, when available, a sample document. Observation counts say what recorded builds reached — compile, typecheck, test — and are counts of neither users nor machines. The sample document says that a reproducible contract exists at that coordinate; its state reflects those sample verification runs. Those two evidence classes are deliberately never added together.
A project compiling is therefore never presented as an individual symbol working. — remains unknown, and a missing sample remains a missing sample. The map records what happened at the coordinate instead of promoting a small set of runs into a universal PASS verdict.
Why testing matters
Documentation → what should work
Code search → how somebody used it
Community → what somebody says worked
CodeSampleX → what was actually tested
The rules that keep the map honest:
- A project compiling is never presented as a symbol working. Observations and verifications are counted separately and never summed.
- Unknown causes stay
UNKNOWN. A wrong HIT is worse than a MISS —NO_SAFE_MATCHis a real answer. - Evidence does not decay, and no cell is marked stale. An observation is one pinned release in one pinned environment bucket at one stage, and none of those move: that a build failed there is exactly as true a year later. What can change is the environment, and a different environment is a different cell.
- Failure causes are reported as probability distributions, never invented certainties.
Install the CLI
The CLI is the local tester: it wraps your real builds, turns their outcomes into anonymous evidence, and answers from the network.
Windows (PowerShell): follow the CLI quick start above for installation, a version check and your first search.
macOS / Linux:
curl -fsSL https://codesamplex.dev/install.sh | sh
That line needs curl and CA certificates, which minimal images (debian-slim, alpine, most agent containers) do not have — and curl … | sh exits 0 when curl is missing, because a pipeline reports the last command's status. Install prerequisites first, or use wget:
apt-get install -y curl ca-certificates # debian / ubuntu slim
apk add --no-cache curl ca-certificates # alpine
wget -qO- https://codesamplex.dev/install.sh | sh # needs neither
On Windows the installer keeps the stable launcher at %LOCALAPPDATA%\csx\csx.exe and adds %LOCALAPPDATA%\csx to the user PATH. On macOS/Linux the default is ${CSX_INSTALL_DIR:-$HOME/.local/bin}/csx; if that directory is not already on PATH, add it:
export PATH="$HOME/.local/bin:$PATH"
csx version # install check — the supported spelling is `csx version`
One binary, one question. csx init shows the contract below and asks a single choice — JOIN COMMUNITY or LOCAL ONLY. Piped into sh, stdin is consumed by the download pipe, so init takes the advertised default: JOIN COMMUNITY. Opt out any time with csx init --local-only; both mode flags are re-runnable and non-interactive. For scripted or CI setups: csx init --community --yes --no-agents.
PurplePulse v2 activation sends only project_id, the persisted random install_id, version, OS, platform (cli or mcp), schema_version: 2, and optional environment at most once per UTC day; DO_NOT_TRACK=1 or CSX_TELEMETRY=0 disables it, and CI/container/serverless runs do not send production telemetry.
Test and check
csx run -- pnpm build # wrap a build/test; its result becomes sanitized evidence
csx search "axios multipart upload" # verified answers graded for YOUR environment
csx --debug search "axios multipart upload" # same answer plus local decision trace
csx hook status # see which supported coding-agent hooks are installed
csx hook check # prove the failure-hook path with a throwaway failing build
csx scan # record public dependency usage without running a build
csx stats # local dashboard: cache, hits, adoption, queues
csx ui # browser dashboard + privacy preview
csx sync # manually refresh shards / flush queues when needed
csx mcp-config # print MCP client configuration
csx update check # verify whether a signed update is available
In community mode, csx init already performs a bounded first cache warm and starts the background sync daemon. A healthy new install should not need a ritual csx sync before its first question. If the installer says the warm was partial or unavailable, csx sync is the explicit recovery path; csx sync --uploads-only flushes queued uploads without doing a shard rescan. Inside a sample-author session (CSX_SESSION_TOKEN is set), sync always uses that upload-only path with a five-minute deadline, including direct binary invocations; cancellation returns a nonzero status and preserves pending data.
local-only is intentionally different: automatic network access is disabled, so it may have a cold compatibility cache by design. Re-running csx init --community is the explicit way to join the network later.
csx search grades every result against the recorded target environment — EXACT, COMPATIBLE, ADAPTATION_REQUIRED, REFERENCE_ONLY, or NO_SAFE_MATCH — and lists the concrete environment delta rather than pretending a nearby run is identical.
Automatic failure lookup
The hook path is the part an agent should not have to remember. For supported coding agents, a failed shell build can be routed through CodeSampleX automatically. The hook only intervenes for recognized build/test commands, sends no raw log, and says nothing when there is no safe match. Use csx hook off to disable it, and csx hook check whenever you want measured proof that the registered hook still fires.
Verified samples
A sample is not a snippet. It is a minimal, content-addressed project (sha256:<hex> of its canonical artifact) with a contract: assertions that were executed offline in a pinned container and passed. Pinned by image digest, not by tag — the tag is an alias for readers, the digest is what runs — and the signed receipt names the exact image reference, so anyone can re-run the same bytes rather than take the word for it (docs/adapters.md). The clean-room authoring loop is CLI-only:
csx sample propose --goal "upload a file with axios" # sanitized brief + scaffolded workspace
csx sample create <dir> # ingest the clean-room project
csx sample preview <id> # show EVERYTHING that would be published
csx sample verify <id> # resolve → compile → contract, sandboxed
csx sample publish <id> # requires typing exactly "yes"; leakage findings hard-refuse
csx sample pending # list agent-prepared drafts waiting for human review
Use csx login github if you want sample publication attributed to your GitHub identity; anonymous publishing remains an explicit CLI choice. Publishing scans for secrets, paths, project names and private URLs — findings block publication with no override flag. Uploading sample source is deliberately not an MCP capability; only a human at the CLI can publish.
Findings
Where does it break? Findings is the measured contradiction list: what the documentation (or common belief) says, next to what the contract measured — documentation mismatches, environment-specific failures, version boundaries. Every line links to the published sample whose contract proves it, so you can re-run the measurement and disagree.
Machine-derived findings grow from published samples whose authors recorded the belief they correct; nobody edits a page to add them.
Dependency atlas
Dependencies reads the recorded dependency graph from the child side: which parent releases pulled this exact dependency release? That is useful for blast-radius and upgrade questions that a package page cannot answer by itself. An edge means a resolver placed those releases together in an observed project; it is deliberately not presented as proof that the pair is compatible.
Coverage gaps
Gaps is the corpus-completeness view. It lists what each coordinate is still missing across three independent assets — Sample, Evidence, Dependency — rather than ranking only what somebody happened to search for. The demand queue still exists as GET /v1/wanted for automation and scheduling, but the public website uses /gaps because demand and completeness are different questions.
Evidence and grading
Why trust a cell? Every result carries its evidence class, weak → strong:
| Grade | What actually happened |
|---|---|
USAGE_OBSERVATION |
a real project built/typechecked/tested with the package — observed, weak |
ADOPTION_EVIDENCE |
someone applied a sample and reported whether the build then passed |
SAMPLE_VERIFICATION |
the sample's contract executed in a pinned container and passed |
CROSS_PASS |
a peer key other than the one that published it re-ran it and it passed again |
MATRIX_PASS |
passing receipts span ≥2 OS/runtime-major/browser-family boundaries |
STABLE |
≥3 distinct peer keys pass it, no failure recorded for 30 days |
A peer is a key, not a person and not a machine. A peer id is the hash of a self-generated ed25519 key with no registration behind it, so one operator can hold as many as they run workers. "Distinct peer keys" means the same coordinate was reported from more than one place; it is never a head count, and nothing here identifies who ran anything.
Sample pages also badge the verification ladder L0_SOURCE_ONLY → L5_MATRIX_PASS, and matrix cells carry confidence (HIGH/MEDIUM/LOW), elevated-failure flags, and last-seen dates. Only signed v2 receipts may claim resolvedPackages — the versions the verifier actually installed, not the versions an author typed; snapshots file each receipt under the version that really ran.
The public counters are a rollup, available as JSON without an account:
curl -fsSL https://codesamplex.dev/v1/stats
| Field | What it counts |
|---|---|
packages / symbols |
coverage: public package names and observed symbols in the compatibility data |
evidence |
accepted observation records; not users, projects, or verified samples |
verifiedSamples |
distinct samples with a sandbox contract-PASS receipt |
peers / projectsMonth |
distinct anonymous daily/monthly contributor buckets |
activeInstallations1d / activeInstallations7d / activeInstallations30d |
distinct anonymous presence tokens from ordinary or external clients in the current aligned UTC 1/7/30-day epochs; these are not sliding windows or counts of people |
postHitBuildsReported |
adoption reports that included a measured PASS or FAIL |
CodeSampleX does not yet measure reliable unique/active users, live MCP processes, or successful installs. Any estimated* field in the stats response is explicitly formula-based and must not be read as a measured count. Measurement is cleanly partitioned into two distinct layers — internal retrieval quality vs user outcome value — under field-first guardrails with no invented uplift (docs/measurement-layers.md).
CodeSampleX MCP questions
What does CodeSampleX record?
It records real builds on real developer machines, including the environment, stage, structured termination, and normalized failure fingerprints.
How can I use CodeSampleX without installing the CLI?
You can use the public REST API to query the network via HTTPS requests without needing an account or client library.
What happens if no verified match is found for my environment?
The search result will return a grade of NO_SAFE_MATCH, indicating that no verified match was found for your specific case.
Can CodeSampleX help with build failures?
Yes, it can install an optional build-failure hook into supported coding agents that automatically searches for solutions when a build step fails.