Solid SDK with excellent docs and clear governance, but pre-alpha status and PR restrictions create friction for newcomers wanting to contribute.
last scored 2026-06-15
Readiness lenses
The same repo, two ways: how ready it is for an AI coding agent, and for a human newcomer. Switch lenses to see each one's score and checks.
How ready the repo is for an AI coding agent to read, build, and operate it.
24 of 35 checks passed across 6 categories.
Machine Orientation
4 checks passed4 problems found
- lowAgent instructions stay lean
A bloated instructions file burns context and measurably hurts more than it helps.
Fix: Trim AGENTS.md to the load-bearing commands and conventions; link out to the rest.
- lowllms.txt present
An llms.txt is the emerging machine-orientation standard — a curated map for LLMs.
Fix: Add an llms.txt pointing at the key docs and entry points.
- lowTopics set
GitHub topics situate the repo's domain and stack for an agent at a glance.
Fix: Add a few GitHub topics describing the domain and stack.
- lowArchitecture doc
An ARCHITECTURE doc hands an agent the module map instead of making it infer one.
Fix: Add an ARCHITECTURE.md describing the major components and how they fit.
- README present — An agent reconstructs what the repo is and how to work in it from the README first.
- Agent instructions file — AGENTS.md / CLAUDE.md is the direct, machine-read channel for entry points and conventions.
- Repository description set — The one-line description is the fastest orientation signal an agent reads.
- Contribution conventions are written down — A contributor guide is where an agent learns the branch, commit, and review conventions it must follow.
Reproducible Setup
3 checks passed3 problems found
- mediumContainer or dev-container
A Dockerfile / compose / devcontainer removes 'works on my machine' from setup.
Fix: Add a Dockerfile, a compose file, or a .devcontainer so the environment is declared, not assumed.
- lowEnv template present
A .env.example tells an agent which configuration keys it must supply to run.
Fix: Ship a .env.example listing every required key with placeholder values.
- lowDev container
A .devcontainer gives an agent a one-command, fully-declared environment.
Fix: Add a .devcontainer so the toolchain is declared, not assumed.
- Lockfile committed — Without a lockfile two clones can resolve different dependency trees — the build isn't reproducible.
- Runtime / toolchain pinned — An unpinned runtime makes an agent guess the version a clean environment needs.
- Version pins are exact — A floating pin (a bare major, or a range) still drifts between installs.
Code Navigability
1 check passed1 problem found
- lowTypeScript strict mode on
Strict typing gives an agent typed signatures to anchor an edit on, not guesses.
Fix: Turn on `strict` in tsconfig.json.
- Conventional source layout — A recognised src/ · lib/ · app/ layout lets an agent localise code without spelunking.
Verification Surface
5 checks passed2 problems found
- mediumTest command defined
A `test` script is the documented, discoverable way to run the suite.
Fix: Add a `test` script (package.json / Makefile / Taskfile) that runs the suite.
- lowTask runner present
A Makefile / Taskfile / justfile gives an agent a single index of the project's commands.
Fix: Add a Makefile / Taskfile / justfile collecting the common commands.
- Tests present — Runnable tests are the ground truth an agent checks its own edits against.
- Lint command defined — A linter an agent can run catches a class of mistakes before they ship.
- CI configured — Readable CI is the feedback loop an agent reads to know what 'green' means here.
- Typecheck command — A typecheck script lets an agent catch type errors before they ship.
- Build command — A documented build command is the discoverable way for an agent to produce artifacts.
Agent Safety
8 checks passed0 problems found
- No committed .env — A tracked real .env hands secrets to anything — including an agent — that reads the repo.
- No exposed secrets — Secret-shaped literals in tracked files are a live credential leak.
- .gitignore covers env files — An ignore rule for .env is what keeps the next careless commit from leaking secrets.
- CODEOWNERS present — CODEOWNERS marks the 'don't touch without review' zones an agent should respect.
- Automated dependency updates — Dependabot / Renovate keeps dependencies patched without a human in the loop.
- .gitignore present — A .gitignore is the first guard against an agent committing secrets or build junk.
- Security policy — A SECURITY.md is where an autonomous security agent reads this repo's rules before acting on it.
- License makes the code reusable — Without a license an agent cannot safely copy, redistribute, or vendor any of this code.
Context Economy
3 checks passed1 problem found
- lowGenerated / vendored files marked
A .gitattributes linguist marker tells tools (and agents) what to skip.
Fix: Mark generated/vendored paths in .gitattributes (linguist-generated / linguist-vendored).
- Dependencies not vendored in — A committed node_modules / vendor tree drowns the real signal an agent needs.
- Build output not committed — Generated dist/ · build/ output is noise an agent has to read past.
- No oversized source file — A single file in the hundreds of KB blows past an agent's effective context window.
How ready the repo is for a human newcomer to understand, set up, and contribute.
72 / 10015 of 25 checks passed across 6 categories.
First Impression
82Clear purpose and scope, but pre-alpha status and v2 development context are front-and-center.
The README immediately states this is the TypeScript SDK for Model Context Protocol, explains the architecture (server/client libraries, middleware), and provides installation instructions and a working code example. However, the banner warnings about pre-alpha v2 status and PR restrictions for newcomers dominate the first screen, and no visual demo or link to a live playground exists. A newcomer understands what it is but may hesitate given the prominent "we're restricting PRs to contributors only" message.
Getting Running
75Installation and quickstart are straightforward, but dependency pinning and local development setup require some digging.
NPM install commands are clear and copy-pasteable for the main packages (@modelcontextprotocol/server and @modelcontextprotocol/client). The README includes a minimal working example and links to step-by-step quickstart tutorials. However, the monorepo uses pnpm@10.26.1 (specified in package.json) and the snapshot does not show a lockfile or explicit setup instructions for running the entire monorepo locally from scratch. A newcomer wanting to contribute would need to infer pnpm commands from the scripts in package.json rather than finding a clear "development setup" section.
Finding Your Way
80Good module organization and documentation, but the monorepo structure and v2 API changes are not visually mapped out.
The README clearly lists the main packages (server, client, middleware) and points to examples and detailed guides (Server Guide, Client Guide, FAQ). The file tree shows organized directories (packages/client, packages/server, examples/), and the codebase has comprehensive doc files (server.md, client.md, migration.md). However, there is no architecture diagram or high-level monorepo layout explanation, and the migration docs suggest significant v2 API changes from v1 that a newcomer exploring the codebase may find confusing without explicit mapping.
Path to Contribute
58Contribution guidelines exist and are detailed, but PR restrictions for non-contributors and the "discuss first" policy create a barrier to low-friction entry.
CONTRIBUTING.md is comprehensive, with clear issue labels (good first issue, help wanted, ready for work), guidance on what counts as significant work, and explicit branching rules. However, the README and CONTRIBUTING both highlight that **PRs are restricted to contributors only** and work requires prior issue discussion before coding—even for small bugs. While this is a reasonable governance choice for a pre-alpha SDK, it directly contradicts the typical newcomer workflow of "pick an issue → code → open a PR" and signals that casual contributions are unwelcome. The barrier to becoming an official contributor is not explained.
Signs of Life
88Active development, recent commits, and clear release pipeline signal a healthy, well-maintained project.
The snapshot shows 12,670 stars, 450 open issues, a commit dated 2026-06-15, active GitHub workflows (conformance testing, deployment, release), and a detailed .changeset/ directory with dozens of tracked changes. The README mentions v2 is in development with a Q3 2026 stable release target, v1 receives ongoing bug fixes, and security policy is documented (SECURITY.md exists). The presence of automated CI/CD, conformance tests, and documented release cadence all indicate an actively maintained project with clear ownership.
Open Door
72Apache 2.0/MIT licensing, CODE_OF_CONDUCT, and SECURITY policy are all present, but the "contributors only" PR gate weakens the sense of openness.
The LICENSE file states dual licensing (Apache 2.0 for new contributions, MIT for existing code), a CODE_OF_CONDUCT.md exists, and SECURITY.md provides a clear vulnerability reporting channel. However, the prominent README warning that **"PRs are temporarily restricted to contributors only"** and the emphasis in CONTRIBUTING that features require pre-discussion send a mixed signal: legally and socially the door is open, but practically the project is gatekeeping PR contributions. This is not unusual for pre-alpha work, but it reduces the sense that newcomers are welcome to step in and propose changes.
First Impression
2 checks passed1 problem found
- lowTopics set
Topics situate the project's domain at a glance and help a newcomer find it.
Fix: Add a few GitHub topics describing the domain and stack.
- README present — The README is the first screen — with none, a newcomer has nothing to land on.
- Repository description set — The one-line description sets expectations before a newcomer even opens the README.
Getting Running
3 checks passed3 problems found
- mediumOne-command environment
A Dockerfile / compose / devcontainer turns a fiddly setup into one command.
Fix: Add a Dockerfile, a compose file, or a .devcontainer for a one-command setup.
- lowEnv template present
A .env.example shows a newcomer exactly which settings they must fill in to run it.
Fix: Ship a .env.example listing every required key with placeholder values.
- lowOne-click dev container
A .devcontainer lets a newcomer start in a cloud IDE with zero local setup.
Fix: Add a .devcontainer for a one-click, batteries-included environment.
- Lockfile committed — Without a lockfile a newcomer's install resolves differently and hits errors the docs don't mention.
- Prerequisite versions pinned — Unpinned prerequisites are the classic 'works on my machine' first-run failure.
- Versions pinned exactly — A floating version still drifts — a newcomer can hit a break the maintainer never saw.
Finding Your Way
2 checks passed1 problem found
- mediumArchitecture / overview doc
An overview hands a newcomer the map instead of making them reconstruct it.
Fix: Add an ARCHITECTURE.md (or a 'Project layout' README section) naming the key directories.
- Conventional source layout — A familiar src/ · lib/ · app/ layout lets a newcomer guess where things live.
- No oversized source file — A single thousand-line file is a wall a newcomer bounces off.
Path to Contribute
2 checks passed4 problems found
- lowIssue templates
Issue templates show a newcomer how to file something useful — and that contributions are welcome.
Fix: Add issue templates under .github/ISSUE_TEMPLATE.
- lowPull-request template
A PR template tells a first-time contributor what a good change includes.
Fix: Add a PULL_REQUEST_TEMPLATE.md.
- lowTest command defined
A documented test command lets a contributor check their change before opening a PR.
Fix: Add a `test` script that runs the suite.
- lowTask runner
A Makefile / Taskfile gives a contributor a single index of the project's commands.
Fix: Add a Makefile / Taskfile collecting the common dev commands.
- CONTRIBUTING guide — A CONTRIBUTING guide is the difference between a guessed and a guided first PR.
- Lint command — A linter lets a first-time contributor catch style issues before review.
Signs of Life
3 checks passed0 problems found
- Tests present — A test suite signals a project that's cared for, not abandoned.
- CI configured — Green CI on every change tells a newcomer the project is actively kept working.
- Automated dependency updates — Dependabot / Renovate activity is a visible heartbeat of ongoing maintenance.
Open Door
3 checks passed1 problem found
- lowLicense is a standard one
A non-standard or custom license is a legal question mark a newcomer won't resolve.
Fix: Use a recognised OSI license so reuse terms are unambiguous.
- License present — With no license the project isn't legally reusable — the door is shut however friendly the README.
- Code of conduct — A code of conduct states the social ground rules that make it safe to step in.
- Security policy — A SECURITY.md tells a newcomer how to report a problem responsibly.
Where the grip slips
- highPath To Contribute+15 pts if fixed
PR restrictions for non-contributors block the typical contribution path
The README and CONTRIBUTING both state that PRs are restricted to contributors only, and the CONTRIBUTING guide requires issue discussion before coding most changes. For a newcomer, this means they cannot follow the standard 'find an issue → code → open a PR' workflow. The barrier to becoming a contributor is never explained, so a newcomer who picks up a 'good first issue' may code a fix only to discover the PR will be rejected.
Fix: Clarify in CONTRIBUTING.md exactly what defines a 'contributor' and what the process is to earn contributor status (e.g., first PR review, maintainer approval). Consider reopening PRs from new contributors once v2 stabilizes, or create a clear alternate path (e.g., 'open a draft PR for feedback before implementation'). If restrictions must remain, escalate this to the top of README to set expectations upfront.
- highGetting Running+12 pts if fixed
No explicit local monorepo development setup instructions
The README and CONTRIBUTING guide code and run examples from published packages (npm install @modelcontextprotocol/server), but there are no instructions for cloning the repo and setting up a local development environment. A newcomer wanting to contribute must infer the setup (pnpm install, pnpm build, pnpm test) from package.json scripts without guidance. This creates friction when debugging or testing changes.
Fix: Add a 'Development Setup' section to CONTRIBUTING.md with: (1) clone + pnpm@10.26.1 requirement, (2) pnpm install && pnpm build commands, (3) how to run tests (pnpm test:all), (4) how to build and test locally before submitting a PR. Optionally link to a DEVELOPMENT.md file with more detail.
- mediumFinding Your Way+10 pts if fixed
No monorepo architecture overview or structure map
The README lists package names and middleware, and file tree shows directories, but there is no visual or narrative map of how the monorepo is organized. A newcomer exploring the codebase to understand the project structure must infer boundaries between packages/client, packages/server, examples/, middleware/, and internal tooling. This is especially important because v2 introduces breaking changes from v1.
Fix: Add a 'Repository Structure' section to README or a new ARCHITECTURE.md file that explains: (1) monorepo layout (pnpm workspaces), (2) each package's purpose (client, server, middleware, test-conformance, codemod), (3) how examples and docs are organized, (4) how to navigate from a problem statement to the right package/file.
- mediumFirst Impression+8 pts if fixed
v1 to v2 migration path is underdocumented in the README
The README heavily emphasizes that v1.x is the stable version and v2 is pre-alpha, and links to v1 API docs, but does not explain to a v1 user or newcomer how/when they should migrate or what has changed. The file tree shows migration.md and migration-SKILL.md, but these are buried and not linked in the README overview.
Fix: Add a subsection in the README under 'Getting Started' or 'Documentation' that says: 'Using v1? See the [migration guide](docs/migration.md) for v2 upgrade path.' Provide a one-sentence summary of the major breaking changes (e.g., 'v2 replaces X with Y; see [migration.md](docs/migration.md) for details').
- mediumGetting Running+8 pts if fixed
No lockfile visible; pnpm version is not pinned in a standard way
The package.json specifies `"packageManager": "pnpm@10.26.1"`, which is good, but the snapshot does not show pnpm-lock.yaml or any other lockfile in the file tree. This makes it unclear whether the dependency graph is reproducible across environments, and a newcomer may clone the repo and hit different transitive versions of dependencies.
Fix: Ensure pnpm-lock.yaml is committed to the repository and visible in the file tree. If it already exists but was excluded from the snapshot, no action is needed, but verify this is documented. If not, run `pnpm install` once and commit the lockfile.
- lowFirst Impression+5 pts if fixed
Multiple pre-alpha warnings risk overwhelming newcomers
The README opens with two large warning blocks (IMPORTANT: v2 is pre-alpha; WARNING: PRs restricted). While honesty is good, the cumulative effect may discourage newcomers from engaging. The pre-alpha status is stated, but no clear 'unstable APIs' or 'here's how to use stable v1' quick link is provided in the same breath.
Fix: Consolidate the two warnings into one concise, actionable banner at the top: 'This is v2 (pre-alpha, stable Q3 2026). Use v1.x for production. PRs from contributors only; see [CONTRIBUTING.md](CONTRIBUTING.md). Questions? [Start here](docs/faq.md).' Link to FAQ or getting-started docs to guide newcomers next steps.
- lowOpen Door+3 pts if fixed
No code of conduct linked in the README
CODE_OF_CONDUCT.md exists in the file tree, but the README does not reference it or any community guidelines. A newcomer looking for the code of conduct has to infer its existence from the file tree.
Fix: Add a 'Code of Conduct' section or footer link in the README pointing to CODE_OF_CONDUCT.md, e.g., 'We are committed to fostering an open and respectful community. See our [Code of Conduct](CODE_OF_CONDUCT.md).'
Show your score
[](https://latch.fyi/modelcontextprotocol/typescript-sdk)Share this analysis
https://latch.fyi/modelcontextprotocol/typescript-sdkFixed some issues? Re-analyze to measure your progress →
Copy the whole report
Grab the entire verdict in one go — a Markdown block for a README or an issue, plain text, or a prompt you can paste straight into an LLM.