createEntities, createRelations, addObservations, deleteEntities,
deleteObservations, and deleteRelations each independently did
load -> mutate -> save with no synchronization. Concurrent tool
calls (e.g. multiple mutations dispatched from one LLM turn) could
race: both read the same starting state, both write back their own
copy, and whichever write landed last silently discarded the other's
changes. Interleaved writes could also corrupt the file outright.
Adds an in-process async mutex (KnowledgeGraphManager.withLock) that
serializes all six mutation methods through a single queue. Read-only
methods (readGraph, searchNodes, openNodes) are unaffected.
Verified: reverting the fix and re-running the new concurrency tests
reproduces the bug exactly (lost entities, lost relations, malformed
JSONL lines). With the fix, all 39 tests pass.
Fixes#1819
Co-authored-by: olaservo <olahungerford@gmail.com>
create_entities and create_relations only de-duplicated against the existing
graph, so passing the same entity name (or identical relation) twice in one
call persisted duplicate records. This contradicts the documented behavior
("Ignores entities with existing names" / "Skips duplicate relations") and
breaks the implicit name-uniqueness invariant the rest of the manager relies
on (e.g. addObservations/deleteEntities key on name).
De-duplicate within the input batch as well, keeping the first occurrence.
Co-authored-by: JSap0914 <JSap0914@users.noreply.github.com>
Co-authored-by: olaservo <olahungerford@gmail.com>
The search_nodes tool accepted an unbounded query string (per
modelcontextprotocol/servers#3537, official servers should constrain
string parameters). An oversized query costs an O(graph) scan per
call with no value. Cap it at 2048 chars via an exported
SearchNodesQuerySchema, and add vitest coverage for the boundary
(at-limit accepted, over-limit rejected, non-string still rejected).
Signed-off-by: fei <204683769+feiiiiii5@users.noreply.github.com>
loadGraph() trusted the persisted memory file and pushed entities and
relations without validating their fields. A corrupted or legacy entry
(e.g. an entity missing entityType, or an observation that is not a string)
would reach searchNodes and crash with "Cannot read properties of undefined
(reading 'toLowerCase')".
Validate each line against the existing EntitySchema/RelationSchema and skip
malformed entries with a warning, so the in-memory graph only ever contains
well-formed data. Malformed JSON lines are skipped as well.
Fixes#2044
delete_entities, delete_observations and delete_relations returned
success: true with a hardcoded "deleted successfully" message regardless
of what matched. An agent that mistypes an entity name is told its memory
is clean while the data is still on disk, and nothing in the response
contradicts that. addObservations throws for the same condition ten lines
above, so the file already disagreed with itself.
Staying quiet is deliberate and documented, so nothing throws and the
output schema is unchanged. The three manager methods now return what
they matched, and the handlers say so. A delete where everything is found
returns the same message it always did.
README updated: the three "Silent operation" bullets described the
absence of an error, which is still true, but read as if the response
said nothing either.
* fix(memory): expand leading ~ in MEMORY_FILE_PATH to the home directory
MCP clients pass MEMORY_FILE_PATH from JSON config, where no shell
expands a leading "~". Because path.isAbsolute("~/memory.jsonl") is
false, the value was joined onto the package directory, so the server
persisted to a literal "~" folder inside the install instead of the
user's intended location.
Add an expandHome() helper that mirrors the one already used by the
filesystem server (src/filesystem/path-utils.ts) and apply it in
ensureMemoryFilePath() before the existing absolute/relative resolution.
Absolute paths, relative paths, and a "~" not at the start are
unaffected. Adds unit tests for expandHome plus an end-to-end test
through ensureMemoryFilePath.
Addresses #1600
* test(memory): use a literal ~/ path in the tilde expansion test
path.join('~', ...) produces a backslash on Windows, which expandHome does
not match, so the test failed there.
---------
Co-authored-by: olaservo <olahungerford@gmail.com>
Fixes#4406. The memory server previously hardcoded serverInfo.version as
"0.6.3", which no longer matched published calendar versions. Resolve
package.json from both source and dist layouts so Docker and npm installs
report the installed package version.
Co-authored-by: syf2211 <syf2211@users.noreply.github.com>
Wrap the addObservations call in an async closure before asserting with
.rejects.toThrow(). This prevents Vitest's global unhandled rejection
handler from capturing the expected error before the assertion can
intercept it, eliminating the false-positive "Unhandled Errors" warning
that was failing CI.
Fixes#3073
Observed on #4714 and #4726: addLabels returned 403 "Resource not
accessible by integration" because pull_request gives fork PRs a
read-only token. The job only calls the GitHub API and never checks
out PR code, so pull_request_target is safe here.
Claude-Session: https://claude.ai/code/session_01CK8vvB229h6orvkokG8YxU
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Update Dockerfile for fetch
Initial patch for podman and SELinux contexts.
* Update Dockerfile for time
podman and SELinux
* Update Dockerfile
* Also include app user / group (securely) such that the build succeeds
* Container app user optional add (#1)
* Update Dockerfile git
* Update Dockerfile fetch
* Update Dockerfile time
* Update Dockerfile
* Update Dockerfile
* Update Dockerfile
---------
Co-authored-by: Ola Hungerford <olahungerford@gmail.com>
validatePath()'s ENOENT fallback checked only the immediate parent
directory before allowing a new path through. Creating a path with
more than one missing level (e.g. a/b/c when none of a, b, c exist)
made the immediate parent check fail with "Parent directory does not
exist", even though fs.mkdir was already called with recursive: true
one level up in the create_directory handler and an existing allowed
ancestor was available further up the tree.
Walk up through missing ancestors until an existing one is found (or
the filesystem root is reached), verifying that ancestor still
resolves inside an allowed directory via realpath. The top-level
lexical containment check already ran against the full target path,
so this only extends how far the existence/symlink check climbs.
Fixes#4629
Co-authored-by: Riley <313779891+rileybuilds@users.noreply.github.com>
Co-authored-by: olaservo <olahungerford@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(sequentialthinking): restore nextThoughtNeeded in the advertised inputSchema required array
commit 1cdf806d (#3533) wrapped nextThoughtNeeded in a z.preprocess-based
coercedBoolean to fix a real footgun (string "false" coercing to true).
zod's toJSONSchema(..., { io: "input" }) treats a z.preprocess()-wrapped
field's input type as unknown, so it silently drops that field from the
emitted required array, even though it carries no .optional(). A client
that builds its call arguments from the advertised schema then omits
nextThoughtNeeded and gets a -32602 Invalid params from the runtime
validator, which still requires it.
Rebuild coercedBoolean as a transform on an explicit z.union([z.boolean(),
z.string()]) instead of z.preprocess. The union gives toJSONSchema a
concrete input type to report, so nextThoughtNeeded stays in required,
while parse behavior (including the case-insensitive string coercion
#3533 added) is unchanged.
Fixes#4651
* test(sequentialthinking): pin nextThoughtNeeded in required and string coercion
Runs against the built server so it checks the schema the SDK emits.
Skips when dist/ is absent, matching server-version.test.ts.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Wo28CHPXyM3DHoLWvKnCK
---------
Co-authored-by: olaservo <olahungerford@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(sequentialthinking): read server version from package.json
Replace the hardcoded 0.2.0 so initialize serverInfo tracks the
package version (0.6.2 in-tree; CalVer after release), matching the
approach used for memory server version sync.
Skip the dist-layout assertion when dist/ is absent so CI's
test-before-build job (and local runs without prepare) still pass.
* test(sequentialthinking): smoke stdio initialize serverInfo.version
Spawn the built server over stdio and assert getServerVersion() matches
package.json (and is not the old hardcoded 0.2.0). Skip when dist/ is
absent so test-before-build CI still passes.
* fix(memory): write the knowledge graph atomically
`saveGraph()` wrote the graph straight to the memory file:
await fs.writeFile(this.memoryFilePath, lines.join("\n"));
`fs.writeFile` opens the target with `'w'`, which truncates it before any
new bytes are written. If the process is interrupted between truncation
and completion — SIGKILL, container or host stop, OOM kill, power loss —
the memory file is left empty or half-written.
That file is the only persistence layer for the knowledge graph, so the
window is small but the loss is total and unrecoverable.
The fix writes to a temporary file in the same directory and renames it
over the target. `rename(2)` is atomic on POSIX filesystems: a reader
sees either the complete old file or the complete new one, never an
intermediate state. Keeping the temp file in the same directory ensures
the rename stays on one filesystem, since cross-device renames fail with
EXDEV. On failure the temp file is removed so no strays accumulate.
Tests added in `__tests__/atomic-save.test.ts`:
- the live memory file is never opened for truncating writes
- a committed graph survives a write that fails midway
- no temporary files remain after a successful write
- the temporary file is cleaned up when the rename fails
- graph contents still round-trip correctly across reloads
The first and fourth fail against the previous implementation.
Full suite: 55 passed (50 existing, 5 new). `tsc --noEmit` clean.
Fixes#4614
* fix(memory): use randomBytes for temp filename to avoid concurrent collision
---------
Co-authored-by: teddiesloco <teddiesloco@users.noreply.github.com>
The move_file tool description and README both state the operation fails if
the destination already exists, but the handler called fs.rename directly,
which silently overwrites the destination. Since this server ships no delete
tool, move_file effectively provided unadvertised, irreversible file
deletion: moving any file onto an existing target destroyed the target.
Add a moveFile helper in lib.ts that rejects when the destination already
exists (checked with lstat, so an existing symlink is detected rather than
followed) and only renames when the target is free, and use it from the
move_file handler. Behaviour now matches the documented contract.
Fixes#4628
* fix(filesystem): preserve file permissions during write and edit operations
The atomic write pattern (write temp file + rename) replaces the original
inode, causing the new file to have default 0644 permissions regardless of
what the original file had. This breaks executable scripts and other files
with non-default permissions.
Fix: capture stat.mode before writing and restore it with chmod after rename.
Fixes both writeFileContent() and applyFileEdits().
* fix(filesystem): mask chmod mode and keep chmod failure from failing the write
Pass origStats.mode & 0o777 to chmod instead of the full st_mode. Move
the chmod out of the try whose catch unlinks the temp file and rethrows,
since rename has already succeeded by then. Add a test that an EPERM
from chmod does not reject the write.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Wo28CHPXyM3DHoLWvKnCK
---------
Co-authored-by: Dustin Rudiger <drudiger@apple.com>
Co-authored-by: olaservo <olahungerford@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
resources/templates.ts:
- `parseResourceId` had a guard that compared the URI against both
`textUriBase` and `blobUriBase` with `&&`. Those prefixes are mutually
exclusive, so the condition is always false and the branch is dead.
Drop it; the SDK's template-based routing already guarantees the URI
prefix is one of the two before the handler runs. The remaining
positive-integer check on `resourceId` is preserved.
resources/subscriptions.ts:
- `sendSimulatedResourceUpdates` had an `else` branch that called
`subscribers.delete(sessionId)` whenever the session wasn't in a URI's
subscriber set, with a comment claiming the session had disconnected.
That conclusion doesn't follow — a session not subscribed to URI A
can still be subscribed to URI B — and the delete is a no-op when
the element is absent anyway. Remove the branch.
No behavioral change. Existing 95 / 95 tests in `__tests__` still pass.
Co-authored-by: Jia Xuan <1060996408+jiaxuan@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Return '0 B' for negative byte values instead of 'NaN B'.
File sizes cannot be negative, so this is a safe default.
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Users hitting the 2.0.0 startup failure land on the README first. Also makes
the three packages qualify for the next release: the release workflow selects
packages by .py/.ts/.md changes, so a dependency-only fix would merge without
publishing.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
mcp 2.0.0 renamed McpError to MCPError and replaced the low-level Server
decorators with constructor handlers. The three servers had no upper bound,
so a fresh uvx install has resolved 2.0.0 since 2026-07-28 and failed to
start: fetch and time raise ImportError on the McpError import, git raises
AttributeError on server.list_tools().
The floor moves to 1.29.0, the last 1.x release. The previous floors (1.0.0
for git, 1.1.3 for fetch, 1.23.0 for time) resolved versions affected by
GHSA-vj7q-gjh5-988w, GHSA-jpw9-pfvf-9f58, and GHSA-hvrp-rf83-w775.
Porting to the v2 SDK is tracked separately.
Closes#4560Closes#4570Closes#4580
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Every filesystem tool operates only on the local filesystem within its allowed
directories — none reaches an open or external world — but none declared the
MCP `openWorldHint` annotation, leaving open-world-hint coverage at 0/14. Set
`openWorldHint: false` on all 14 tools and document it in the README's tool
annotations section.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(filesystem): return valid MCP content type from read_media_file (#4029)
read_media_file returned a content block with type: "blob" for non-image/
non-audio files. "blob" is not a valid MCP content type (the union is
text | image | audio | resource_link | resource), so a strict client rejects
the result on schema validation.
Map the MIME type to a valid block: image/* -> image, audio/* -> audio, and
any other file type -> an embedded resource (the spec-correct carrier for
arbitrary bytes) with a pathToFileURL-encoded uri. Widen the tool's
outputSchema to the matching union and drop the now-unnecessary
`as unknown as CallToolResult` cast so tsc enforces the returned shape.
Tests cover the image, audio, and resource content types, verify the base64
blob round-trips to the original bytes, and assert the resource uri is
percent-encoded (space + non-ASCII) rather than a raw file:// concatenation.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* test(filesystem): assert structuredContent mirrors content in read_media_file tests
The SDK validates content and structuredContent independently against the
outputSchema union, so a refactor that lets the two drift apart (e.g. a
stale image block in structuredContent while content carries the resource)
stays schema-valid and every test stays green. Mirror-equality assertions
on all four callTool cases close that gap (mutation-verified: a schema-valid
drifted structuredContent fails exactly these four assertions).
Also drops a vacuous .not.toBe('blob') assertion that could never add
signal, noting where the real "never blob" guard actually lives (the SDK
client's CallToolResultSchema rejection, upstream of any local assertion).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Per-ref cancellation is for superseded branch amend-pushes; on main,
every merge keeps its own CI run so failures stay attributable to a
specific commit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AViME1R9ES2UXT1uQDx1TG
Previously push-triggered CI ran only on main, so same-repo branches
got no CI until a PR was opened (fork contributions were and remain
covered by pull_request, which fires on open and on every subsequent
push). Run on all pushes, and add a per-ref concurrency group so rapid
amend-pushes cancel superseded runs. Same-repo branches with an open
PR will run under both events; acceptable at this repo's scale.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AViME1R9ES2UXT1uQDx1TG
Releases are now triggered deliberately via workflow_dispatch. The
schedule produced a year of unattended runs stuck awaiting environment
approval, every real release was manually dispatched anyway, and two
runs on the same UTC day collide on the date-based tag. Rename the
workflow to "Release" accordingly and update RELEASING.md.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AViME1R9ES2UXT1uQDx1TG
Review findings: RELEASING.md claimed publishing happens exclusively
from release.yml with no registry tokens, but typescript.yml and
python.yml still carried release:[published] publish jobs — never
fired (releases are created with GITHUB_TOKEN, which suppresses
workflow triggers) and unable to succeed under OIDC (typescript.yml's
still referenced the deleted NPM_TOKEN). Remove both jobs and their
release triggers; the workflows are now pure CI.
Also:
- add skip-existing to the PyPI publish action so re-runs tolerate
already-uploaded files, and describe the per-registry guard
accurately in RELEASING.md (npm aborts; PyPI skips)
- correct the fresh-dispatch note: same-day dispatches collide on the
date-granular tag rather than minting a new version
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AViME1R9ES2UXT1uQDx1TG
RELEASING.md documents the pipeline this PR ships (scheduled/dispatch
CalVer releases, OIDC publishing, retry runbook), with a footer noting
the planned Phase 2 changes tracked in #4463. The doc gets updated
when that work merges, not before.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AViME1R9ES2UXT1uQDx1TG
Rewrite RELEASING.md as the reference for the target process rather
than a snapshot of the interim state: semver via changesets for
TypeScript / CalVer for Python, versions changed only by PRs on main,
publishing triggered by creating a GitHub Release, per-package
registry-diff guard, OIDC trusted publishing with no registry tokens,
and the failed-publish retry runbook. Implementation tracked in #4463.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AViME1R9ES2UXT1uQDx1TG
Describes how packages publish (release.yml + release environment,
trusted publishing on npm and PyPI, no registry tokens, provenance),
what a release run does, and how to recover from a failed publish leg
(rerun --failed within the window, or ride the next release). Linked
from the root README alongside the other maintainer docs.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AViME1R9ES2UXT1uQDx1TG
Review findings from the PR:
- release.py's has_changes() only counted .py/.ts files, so the README
touches meant to enroll the four TS packages in the npm matrix would
have been ignored. Include .md — READMEs ship inside the published
package (npm tarball / PyPI long_description), so doc changes are
release-relevant.
- uv run --frozen pytest for consistency with the job's other uv calls.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AViME1R9ES2UXT1uQDx1TG
Gate both publish jobs on the package's test suite: npm test
--if-present before the npm build/publish, and pytest (when a tests/
or test/ directory exists, matching python.yml's guard) before the
PyPI build/publish. Previously nothing between tagging and publishing
ran a single test.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AViME1R9ES2UXT1uQDx1TG
The NPM_TOKEN used by publish-npm is dead (npm classic-token sunset) —
both June release attempts failed publishing with a disguised auth error
(E404 on the publish PUT) after PyPI legs succeeded. Each
@modelcontextprotocol/* package's npm trusted publisher is being bound to
this workflow (release.yml) + the release environment, so publish-npm now
authenticates via OIDC instead of a token:
- add id-token: write permission to publish-npm (required to mint the
OIDC token; contents: read added explicitly since setting permissions
drops the defaults)
- upgrade the npm CLI in the publish job (trusted publishing requires
npm >= 11.5.1; Node 22 bundles an older npm)
- drop NODE_AUTH_TOKEN from the publish step
Also touch each TypeScript server's README (add everything's missing
License section; link each package's npm page) so scripts/release.py
includes all four packages in the next npm publish matrix — they've been
stranded on npm at 2026.1.26 while PyPI advanced to 2026.6.16.
See #4463 for the rollout plan.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AViME1R9ES2UXT1uQDx1TG
Resolves a fresh batch of Dependabot alerts (disclosed 2026-06-15/16,
after PR #4376 merged) across the fetch, git, and time server lockfiles:
- python-multipart 0.0.27 -> 0.0.32 (CVE-2026-53539 HIGH querystring DoS,
plus CVE-2026-53537/53538/53540 parameter smuggling / buffering)
- cryptography 48.0.0 -> 49.0.0 (GHSA-537c-gmf6-5ccf HIGH, vulnerable
OpenSSL statically linked in wheels < 48.0.1)
- pyjwt 2.12.1 -> 2.13.0 (HIGH + medium JWT advisories)
All three are transitive deps; lockfiles only. Diff scoped to exactly
these 9 version bumps with no other resolution churn. git server tests
unchanged vs base (43 passed; 37 pre-existing Windows tempdir errors).
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(memory): expose knowledge graph as MCP Resource
Register the knowledge graph as a readable MCP Resource at
memory://knowledge-graph, enabling clients to discover and read
the graph via the Resources protocol without invoking a tool.
Mutation tools (create_entities, create_relations, add_observations,
delete_entities, delete_observations, delete_relations) now emit
notifications/resources/updated so subscribed clients see live
graph changes.
Resource registration is extracted into the exported
registerKnowledgeGraphResource() function so it can be unit-tested
in isolation, mirroring the everything server's registration
pattern. New tests assert registerResource is called with the
correct kebab-case name, URI, mime type, and that the handler
returns the graph as JSON in the contents array.
Addresses PR #3323 review feedback:
- kebab-case resource name per CLAUDE.md style guide
- single-line comment per CLAUDE.md style guide
- title metadata for client discoverability
- resource update notifications after mutations
- test coverage matching everything/registrations.test.ts pattern
- README documents the new Resource
* feat(memory): support resources/subscribe for the knowledge-graph resource
PR #3323 emitted notifications/resources/updated after every mutation but
the server only advertised resources.listChanged, so resources/subscribe
returned -32601 and a spec-compliant client could never actually subscribe.
Declare resources.subscribe, add subscribe/unsubscribe request handlers that
track subscribed URIs, and only emit notifications/resources/updated when the
client has subscribed to that URI.
Co-authored-by: Lazreg Raed <lazregraed222@gmail.com>
---------
Co-authored-by: olaservo <olahungerford@gmail.com>
Real fixes (deps):
- python (git/fetch/time): idna 3.10->3.18 (GHSA-65pc), starlette
0.49.1->1.3.1 (GHSA-86qp)
- npm: vitest ^2.1.8->^4.1.8 (critical GHSA-5xrq UI server RCE). vitest 4
pulls vite 8 (rolldown, no esbuild), clearing the esbuild/vite advisories
natively. Remaining root overrides: qs>=6.15.2 (GHSA-q8mj, via express),
hono>=4.12.21 (via @modelcontextprotocol/sdk).
- npm audit: 0 vulnerabilities; all TS (313) + Python (git/fetch/time) suites
and TS builds pass.
Hardening (git_add):
- The repo already mitigates CVE-2026-27735 by using repo.git.add (the git
CLI rejects out-of-tree paths, PR #3164's fix), not repo.index.add (which
did not). Add an explicit path-boundary check in git_add as defense in
depth plus regression tests asserting the security invariant (out-of-tree
paths are never staged), guarding against a regression to repo.index.add.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* url elicitation
* single tool for normal and error path
* Address review feedback on URL elicitation tool
- Remove src/everything/pnpm-lock.yaml (monorepo uses npm workspaces)
- Drop redundant TriggerUrlElicitationSchema.parse(args) in the handler;
destructure directly from args like the other tools, since the SDK
validates against the registered schema before invoking the handler
- Add explicit accept/decline/cancel messaging in the request path,
mirroring trigger-elicitation-request.ts
- Clarify the registerTool count comment in registrations.test.ts
(task-based tools register via registerToolTask, counted separately)
- Add tests covering the no-url / undefined-capability registration
guards, the randomUUID() elicitationId fallback, and the
decline/cancel response paths (100% coverage of the tool)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Add tool annotations to trigger-url-elicitation
Match the annotations block on sibling elicitation tools and the
CLAUDE.md guidance. Uses openWorldHint: true since the tool drives an
external browser flow.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(everything): prevent URL elicitation error-path infinite loop
The trigger-url-elicitation tool's error path (errorPath=true) threw
UrlElicitationRequiredError (-32042) carrying the same URL that failed and
re-threw it on every retry, so clients looped (and tripped their own loop
detection).
- Point the prerequisite elicitation at a different URL
(https://modelcontextprotocol.io) than the failing request.
- Track issued prerequisites by the inputs a client resends on retry
(session + url + caller-supplied elicitationId); a plain retry is then
recognized, ignores errorPath, and proceeds via the request path instead
of re-throwing the prerequisite.
- Update tests and docs accordingly.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(everything): address review on URL elicitation error path
- Replace raw NUL byte delimiters in errorPathKey with the \u0000 escape
sequence so the source stays plain text and the diff is reviewable
(same collision-proof delimiter at runtime).
- Add a one-shot test reset helper + beforeEach so the suite is robust to
the module-level marker state regardless of order.
- Use a dedicated prerequisite message instead of reusing the caller's.
- Document the unbounded-growth tradeoff as a demo simplification and note
the one-shot marker semantics in docs/features.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: evalstate <1936278+evalstate@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* url elicitation
* single tool for normal and error path
* Address review feedback on URL elicitation tool
- Remove src/everything/pnpm-lock.yaml (monorepo uses npm workspaces)
- Drop redundant TriggerUrlElicitationSchema.parse(args) in the handler;
destructure directly from args like the other tools, since the SDK
validates against the registered schema before invoking the handler
- Add explicit accept/decline/cancel messaging in the request path,
mirroring trigger-elicitation-request.ts
- Clarify the registerTool count comment in registrations.test.ts
(task-based tools register via registerToolTask, counted separately)
- Add tests covering the no-url / undefined-capability registration
guards, the randomUUID() elicitationId fallback, and the
decline/cancel response paths (100% coverage of the tool)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Add tool annotations to trigger-url-elicitation
Match the annotations block on sibling elicitation tools and the
CLAUDE.md guidance. Uses openWorldHint: true since the tool drives an
external browser flow.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: cliffhall <cliff@futurescale.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Third-Party Servers section (Official Integrations + Community
Servers) has been superseded by the MCP Registry at
https://registry.modelcontextprotocol.io/. The README already carried a
deprecation note and CONTRIBUTING.md froze new additions. This removes
the list, updates CONTRIBUTING.md to describe the new state, and
refreshes the readme-pr-check workflow's bot comment.
fix(filesystem): ensure bare Windows drive letters normalize to root
Appends path.sep to bare drive letters (e.g. "C:") before calling path.normalize(), preventing them from normalizing to "C:." (current directory on drive) instead of "C:\" (drive root). Includes test coverage with platform mocking.
Fixes#3418
fix(sequential-thinking): use z.coerce for number and safe preprocess for boolean params
Uses z.coerce.number() for number fields and a z.preprocess() helper for boolean fields to handle string-typed parameters from LLM clients. The preprocess approach correctly handles "false" → false, avoiding the z.coerce.boolean() footgun where Boolean("false") === true.
Fixes#3428
fix(git): add missing argument injection guards
Extends existing startswith("-") input validation to git_show, git_create_branch, git_log, and git_branch, preventing user-supplied values from being interpreted as CLI flags by GitPython's subprocess calls to git.
feat(time): add tool annotations
Adds MCP ToolAnnotations to both time server tools (get_current_time, convert_time). Both are read-only, non-destructive, idempotent, and closed-world.
Fixes#3574
feat(sequential-thinking): add tool annotations
Adds MCP ToolAnnotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) to the sequential-thinking tool, bringing it in line with the annotation pattern established by the filesystem server.
Fixes#3403
fix(fetch): handle malformed input without crashing
Changes `raise_exceptions=True` to `raise_exceptions=False` in the fetch server's `Server.run()` call, preventing the server from crashing on malformed JSON-RPC input. This aligns with the SDK's intended default behavior and is consistent with other reference servers.
Fixes#3359
The uv installation section mentioned using uvx but didn't show the
actual command, unlike the PIP section which shows both install and run
commands. This adds the missing `uvx mcp-server-time` command.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Fixes high-severity qs DoS vulnerability (GHSA-6rw7-vpxm-498p).
Remaining moderate-severity issues are in dev dependencies
(esbuild/vite/vitest) and require a breaking vitest v2->v4 upgrade.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Update get-annotated-message description: all tools now have
tool-level annotations, not just this one
- Add missing tool entries: simulate-research-query,
trigger-elicitation-request-async, trigger-sampling-request-async
- Add these tools to the file tree listing
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Previously, `openNodes` and `searchNodes` only returned relations where
BOTH endpoints were in the result set (using `&&`). This silently
dropped all relations to/from nodes outside the set — making it
impossible to discover a node's connections without calling `read_graph`
and filtering the entire dataset client-side.
Changed the filter from `&&` to `||` so that any relation with at least
one endpoint in the result set is included. This matches the expected
graph-query semantics: when you open a node, you should see all its
edges, not just edges to other opened nodes.
Fixes#3137
Tests updated and new cases added covering:
- Outgoing relations to nodes not in the open set
- Incoming relations from nodes not in the open set
- Relations connected to a single opened node
- searchNodes returning outgoing relations to unmatched entities
Co-authored-by: Cursor <cursoragent@cursor.com>
The upstream main added simulate-research-query and async tools that
use server.experimental.tasks.registerToolTask. Update mock servers
to include this API.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Removed ~29 tests that were adding noise rather than coverage:
- Registration boilerplate tests (16): redundant with registrations.test.ts
- Redundant role/type checks (3): consolidated into behavioral tests
- "Should not throw" tests (6): consolidated into single lifecycle test
- Constant identity tests (2): provided no safety net
- expect(true).toBe(true) test (1): replaced with actual assertion
- Weak capability test (1): removed, handler check already exists
Strengthened remaining tests:
- Resource templates test now verifies specific resource names
- File resources test now asserts registerResource was called
Test count: 124 → 95 (29 removed)
Coverage unchanged at ~71%
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The httpx library renamed 'proxies' to 'proxy' in version 0.28.0.
This updates the fetch server to use the new parameter name and
removes the version cap on httpx.
Fixes#3287
Previously only get-annotated-message had ToolAnnotations. Now all 18
tools explicitly declare readOnlyHint, destructiveHint, idempotentHint,
and openWorldHint so the server serves as a complete reference for
developers implementing tool annotations per the MCP spec.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The project uses Vitest, not Jest. Replace jest.fn() with vi.fn()
to fix the ReferenceError in the relative path resolution test.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add comprehensive test coverage for the fetch server:
- TestGetRobotsTxtUrl: 6 tests for URL parsing
- TestExtractContentFromHtml: 3 tests for HTML-to-markdown conversion
- TestCheckMayAutonomouslyFetchUrl: 5 tests for robots.txt handling
- TestFetchUrl: 6 tests for URL fetching with various scenarios
Total: 20 tests covering:
- URL parsing and robots.txt URL generation
- HTML content extraction and markdown conversion
- robots.txt permission checking (401, 403, 404, allow/disallow)
- HTTP response handling (success, errors, raw mode)
- Proxy support
Also adds pytest and pytest-asyncio as dev dependencies.
On macOS, /tmp is a symlink to /private/tmp. When users specify /tmp
as an allowed directory, the server was resolving it to /private/tmp
during startup but then rejecting paths like /tmp/file.txt because
they dont start with /private/tmp.
This fix stores BOTH the original normalized path AND the resolved
path in allowedDirectories, so users can access files through either
form. For example, with /tmp as allowed directory, both /tmp/file.txt
and /private/tmp/file.txt will now be accepted.
Fixes#3253
When a tool like `gzip-file-as-resource` is called multiple times with the
same output name (especially the default `README.md.gz`), the server would
throw "Resource already registered" because the SDK doesn't allow
registering duplicate URIs.
This fix:
- Tracks registered resources by URI in a module-level Map
- Before registering a new resource, checks if the URI already exists
- If it does, removes the old resource using the SDK's `remove()` method
- Then registers the new resource with fresh content
This allows tools to be called repeatedly with the same parameters without
errors, which is important for LLM agents that may retry tool calls.
Found using Bellwether (https://bellwether.sh), an MCP server validation tool.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Follow-up to https://github.com/modelcontextprotocol/servers/pull/3233.
Configure Dependabot to automatically detect updates to the actions used in
GitHub Actions (e.g., `actions/checkout`) and create pull requests for them.
Based on experience, checking for updates on a weekly interval should work well.
"Everything Server crashes when multiple clients reconnect"
* In index.ts
- added a variable to hold the initialize timeout
- store the timeout in the oninitialized handler
- clear the timeout in the cleanup callback
* In roots.ts
- In the catch block of syncRoots, log the error to the console via .error rather than attempting to send to the client because the most probable case here is that we don't have a connection.
"Everything Server crashes when multiple clients reconnect"
* In index.ts
- added a variable to hold the initialize timeout
- store the timeout in the oninitialized handler
- clear the timeout in the cleanup callback
* In roots.ts
- In the catch block of syncRoots, log the error to the console via .error rather than attempting to send to the client because the most probable case here is that we don't have a connection.
* In simulate-research-query.ts
- remove redundant local variable in getTask
* Everywhere else, prettier.
- Use params.task instead of params._meta.task for task metadata
- Remove pollInterval from task requests (only available on result)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
move_file deletes the source file, which is a destructive operation.
Updated annotations and README documentation to reflect this.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Previously, the server would crash if any configured directory was
unavailable (e.g., unmounted external drive). Now it:
- Filters out inaccessible directories with a warning
- Continues operating with remaining accessible directories
- Only fails if NO directories are accessible
Fixes#2815
Implement graceful degradation for elicitation on HTTP transport:
- STDIO: Full elicitation works via sendRequest
- HTTP: Catches elicitation failure, uses default interpretation
- Task completes successfully on both transports
simulate-research-query now uses try-catch around sendRequest and
includes explanatory message when elicitation is skipped on HTTP.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update documentation to reflect that simulate-research-query now sends
elicitation requests directly from the background task instead of using
the tasks/result side-channel approach.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Instead of waiting for the client to call tasks/result to trigger
elicitation, the server now sends elicitation/create directly from
the background process using sendRequest. This simplifies the flow:
- Server sends elicitation proactively when clarification is needed
- Client receives and handles it via existing elicitation handler
- Task resumes and completes after receiving the response
- Client's polling sees completed status
This approach avoids requiring the client to detect input_required
status and call tasks/result as a side-channel.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes CI failures in PR #3220.
PR #3220 updated `mcp` library from 1.0.0 to 1.23.0, which caused test
failures due to a breaking change in `McpError` constructor API.
The `McpError` constructor now expects an `ErrorData` object instead of
a plain string message. This commit fixes the usage in `get_zoneinfo()`
function to use `ErrorData(code=INVALID_PARAMS, message=...)`.
```console
Error before fix:
AttributeError: 'str' object has no attribute 'message'
```
Also updates `mcp` dependency to >=1.23.0 in pyproject.toml to ensure
compatibility with the new API.
Add readOnlyHint, destructiveHint, idempotentHint, and openWorldHint
annotations to the tool config. Update docs to reflect that this tool
now demonstrates both tool-level and content annotations.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add tools that demonstrate bidirectional MCP tasks where the server
sends requests to the client for async execution:
- trigger-sampling-request-async: Send sampling request with task
params, client creates task and executes LLM call in background,
server polls for completion and retrieves result
- trigger-elicitation-request-async: Same pattern for user input,
useful when user may take time to fill out forms
Both tools:
- Check client capabilities (tasks.requests.sampling/elicitation)
- Accept both CreateTaskResult and direct result responses
- Poll tasks/get for status updates
- Fetch final result via tasks/result
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add tasks capability with list, cancel, and requests.tools.call
- Add InMemoryTaskStore and InMemoryTaskMessageQueue from SDK experimental
- Add simulate-research-query tool demonstrating task lifecycle
- Task demonstrates working -> input_required -> completed status flow
- Uses elicitation for ambiguous queries when client supports it
Closes#3037🦉 Generated with [Claude Code](https://claude.ai/code)
Adds a GitHub Actions workflow that:
- Detects PRs that only modify README.md
- Comments explaining we no longer accept new server additions
- Directs contributors to the MCP registry instead
- Allows updates/removals via /i-promise-this-is-not-a-new-server
- Uses labels (readme: pending / readme: ready for review) for filtering
- Minimizes bot comment after confirmation to reduce clutter
Claude-Generated-By: Claude Code (cli/claude-opus-4-5=100%)
Claude-Steers: 10
Claude-Permission-Prompts: 0
Claude-Escapes: 0
Use Git CLI directly instead of GitPython index API to ensure proper
path validation and prevent option injection. The '--' separator ensures
file paths starting with '-' are handled correctly.
Add validation to ensure file paths are within repository boundaries
before staging. This prevents potential issues with relative paths
and improves overall robustness of the git_add function.
The syncRoots call should be idempotent, requesting roots if they haven't been yet for the session, but always retuning the cached roots otherwise. That could be deferred but setting the handler for roots_list changed note should not.
* In server/roots.ts
- only set the notification handler and call for initial roots list if the roots aren't already cached for this client.
* In server/index.ts
- in the oninitialized handler
- get the sessionId from the transport
- set a 350ms timeout to call syncRoots with the server and sessionId
- this delay cause it to run after the `notifications/initialized` handler finishes, otherwise, the request gets lost.
* All other changes attributable to prettier
* In server/roots.ts
- in syncRoots, if roots are supported fetch them
* In get-roots-list.ts,
- Don't import and inspect current roots map, just call syncRoots to get the list.
* In how-it-works.md,
- added a section on conditional tool registration
* In server/index.ts
- import registerConditionalTools
- in an oninitialized handler for the server, call registerConditionalTools
- removed clientConnected from ServerFactoryResponse and all mentions in docs
* In tools/index.ts
- export a registerConditionalTools function
- refactor/move calls to registerGetRootsListTool, registerTriggerElicitationRequestTool, and registerTriggerSamplingRequestTool out of registerTools and into registerConditionalTools
* In server/roots.ts
- only act if client supports roots
- remove setInterval from call to requestRoots. It isn't happening during the initialze handshake anymore, so it doesn't interfere with that process if called immediaately
* In get-roots-list.ts, trigger-elicitation-request.ts, and trigger-sampling-request.ts,
- only register tool if client supports capability
* Throughout the rest of the files, removing all references to `clientConnected`
* In get-roots-list.ts, query the server's cache of the latest roots from the client and only request the list from the client if it doesn't exist.
* In roots.ts, export the roots map
* In get-roots-list.ts, query the server's cache of the latest roots from the client and only request the list from the client if it doesn't exist.
* In roots.ts, export the roots map
Finalized Roots list changed handling and initial request. Final fit and finish work.
* Updated architecture.md
- Added links to other docs
- Refactor/extracted sections into extension.md, features.md, how-it-works.md, startup.md, and structure.md
* Removed everything.ts
- all features are ported
* In roots.ts
- refactor/renaned setRootsListChangedHandler to syncRoots
- refactor handler logic to requestRoots function
- Calls for roots list directly to get initial list
* In server/index.ts
- import setRootsListChangedHandler
- in clientConnected callback
- call setRootsListChangedHandler passing server and sessionId
* In sse.ts, stdio.ts, and streamableHttp.ts
- update inline and function docs
* In index.ts,
- updated usage output
* In server/index.ts
- refactor/extracted readInstructions to resources/index.ts
- defined ServerFactoryResponse response type
Adding Trigger Elicitation Request and Get Roots List tools
* Updated architecture.md
* Added roots.ts
- tracks roots by sessionId
- setRootsListChangedHandler
- listens for roots changed notification from the client
- updates the roots map by sessionId
- sends log notification or error to the client
* In server/index.ts
- import setRootsListChangedHandler
- in clientConnected callback
- call setRootsListChangedHandler passing server and sessionId
* In sse.ts, stdio.ts, and streamableHttp.ts
- receive clientConnected from server factory
- call clientConnected when server is connected to transport
* Added get-roots-list.ts
- registerGetRootsListTool
- Registers the 'get-roots-list' tool with the given MCP server.
* Added trigger-elicitation-request.ts
- registerTriggerElicitationRequestTool
- registered tool sends an elicitation request that exercises all supported field types
* In tools/index.ts
- imports registerTriggerElicitationRequestTool and registerGetRootsListTool
- in registerTools
- call registerTriggerElicitationRequestTool and registerGetRootsListTool, passing server
Adding Trigger Elicitation Request and Get Roots List tools
* Updated architecture.md
* Added roots.ts
- tracks roots by sessionId
- setRootsListChangedHandler
- listens for roots changed notification from the client
- updates the roots map by sessionId
- sends log notification or error to the client
* In server/index.ts
- import setRootsListChangedHandler
- in clientConnected callback
- call setRootsListChangedHandler passing server and sessionId
* In sse.ts, stdio.ts, and streamableHttp.ts
- receive clientConnected from server factory
- call clientConnected when server is connected to transport
* Added get-roots-list.ts
- registerGetRootsListTool
- Registers the 'get-roots-list' tool with the given MCP server.
* Added trigger-elicitation-request.ts
- registerTriggerElicitationRequestTool
- registered tool sends an elicitation request that exercises all supported field types
* In tools/index.ts
- imports registerTriggerElicitationRequestTool and registerGetRootsListTool
- in registerTools
- call registerTriggerElicitationRequestTool and registerGetRootsListTool, passing server
* Updated architecture.md
* Refactor/renamed get-sampling-request.ts to trigger-sampling-request.ts
- use trigger instead of get throughout
* In tools/index.ts
- sorted display order
[WIP] Adding Gzip File as Resource tool
* Updated architecture.md
* Added gzip-file-as-resource.ts
- imports getSessionResourceURI and registerSessionResource from session.ts
- exports registerGZipFileAsResourceTool
- the registered tool
- validates the input URI
- fetches the file safely
- compresses it
- creates and registers the resource
- returns resource or resource link
* In tools/index.ts
- import registerGZipFileAsResourceTool
- in registerTools,
- call registerGZipFileAsResourceTool passing server
* Added resources/session.ts
- getSessionResourceURI gets a uri to the specified name
- registerSessionResource registers the session-scoped resource and returns a resource link
[WIP] Adding Gzip File as Resource tool
* Updated architecture.md
* In resources/files.ts
- remove 'Docs: ' from resource name
* In resources/templates.ts
- use blob instead of text in resource content
For tools where we seek to get some response from the server, renamed as an action, e.g., "Get Sum" rather than "Add" or "Get Annotated Message" rather than "Annotated Message", so that it's clear what the intent of the tool is in a quick review.
* Updated architecture.md
* Refactor/renamed add.ts to get-sum.ts
* Refactor/renamed annotated-message.ts to get-annotated-message.ts
* In tools/index.ts
- sorted presentation order
Adding get-structured-content tool
* Updated architecture.md
* added get-structured-content.ts
- Registers the 'get-structured-content' tool with the provided McpServer instance.
- The registered tool processes incoming arguments using a predefined input schema,
generates structured content with weather information including temperature,
conditions, and humidity, and returns both backward-compatible content blocks
and structured content in the response.
Adding the get-resource-reference and get-resource-reference tools
* Updated architecture.md
* Added get-resource-links.ts
- Registers the 'get-resource-reference' tool with the provided McpServer instance.
- The registered tool retrieves a specified number of resource links and their metadata.
* In get-resource-reference.ts
- fixed tool description
* In tools/index.ts
- import registerGetResourceLinksTool
- in registerTool
- call registerGetResourceLinksTool
Adding the get-resource-reference tool
* Updated architecture.md
* In prompts/resource.ts
- Refactor/extracted the prompt argument completers into exported functions in resources/templates.ts
- Refactor/extracted BLOB_TYPE, TEXT_TYPE, and resourceTypes into exported constants in resources/templates.ts as RESOURCE_TYPE_BLOB, RESOURCE_TYPE_TEXT, and RESOURCE_TYPES
- In resources/templates.ts
- refactor renamed index to resourceId throughout for consistency with prompts and tool references
* Added tools/get-resource-reference.ts
- Registers the 'get-resource-reference' tool with the provided McpServer instance.
- uses enum and number schema for tools to provide resourceType and resourceId arguments. Completables don't work for tool arguments.
- Returns the corresponding dynamic resource
* In tools/index.ts
- imported registerGetResourceReferenceTool
- in registerTools
- called registerGetResourceReferenceTool
Adding the annotated message tool
* Updated architecture.md
* Added annotated-message.ts
- registers a tool that returns a message with annotations on different content types
* In package.json
- updated TS SDK version
Added print-env, and sampling-request tools
* Updated architecture.md
* In tools/index.ts
- import registerPrintEnvTool and registerSamplingRequestTool
- in registerTools
- call registerPrintEnvTool and registerSamplingRequestTool
* Added tools/print-env.ts
- registers a tool that takes no args and returns the environment variables
* Added tools/sampling-request
- registers a tool that
- takes prompt and maxTokens args
- sends client a sampling request
- returns the client response in the result
Added long-running-operation tool and improved comments in all tools
* Updated architecture.md
* In tools/
- add.ts
- echo.ts
- toggle-logging.ts
- toggle-subscriber-updates.ts
- Add better function and inline docs
* Added tools/long-running-operation.ts
- similar implementation as in everything v1
* In tools/index.ts
- import registerLongRunningOperationTool
- in registerTools
- registerLongRunningOperationTool
Added tools to toggle simulated logging and resource updates on and off rather than have them start immediately upon connection
* Updated architecture.md
* In server/index.ts
- remove import of beginSimulatedResourceUpdates and beginSimulatedLogging
- remove clientConnected from createServer factory result
* In tools/index.ts
- import registerToggleLoggingTool and registerToggleSubscriberUpdatesTool
- in registerTools
- call registerToggleLoggingTool and registerToggleSubscriberUpdatesTool
* In logging.ts
- in beginSimulatedLogging
- refactor extract inline interval callback into function sendSimulatedLoggingMessage
- call sendSimulatedLoggingMessage right away to send the first message
- supply sendSimulatedLoggingMessage as interval callback
* In subscriptions.ts
- remove import of Transport
- remove transports map
- in beginSimulatedResourceUpdates()
- change arguments to server and sessionId
- check for the subsUpdateInterval for the session
- remove all transport storage and interaction
- instead use the server to send the notification
- in stopSimulatedResourceUpdates()
- remove management of transports map
* In stdio.ts, sse.ts, and streamableHttp.ts
- remove destructure and calling of clientConnected
* Added tools/toggle-logging.ts
- registers a tool that
- takes no arguments
- tracks clients that have been enabled by session id in a set
- if client isn't enabled,
- calls beginSimulatedLogging
- adds session id to client set
- else
- calls stopSimulatedLogging
- deletes session id from client set
- returns a message explaining what was done including what to expect when logging is enabled
* Added tools/toggle-subscriber-updates.ts
- registers a tool that
- takes no arguments
- tracks clients that have been enabled by session id in a set
- if client isn't enabled,
- calls beginSimulatedResourceUpdates
- adds session id to client set
- else
- calls stopSimulatedResourceUpdates
- deletes session id from client set
- returns a message explaining what was done including what to expect when logging is enabled
Adding simulated logging and refactoring subscriptions to not need to track transports
* Updated architecture.md
* In server/index.ts
- remove import of Transport
- import beginSimulatedLogging and stopSimulatedLogging
- in clientConnected()
- change argument to sessionId? instead of transport
- add call to beginSimulatedLogging
- send server and sessionId to beginSimulatedResourceUpdates and beginSimulatedLogging
- in cleanup()
- add call to stopSimulatedLogging passing sessionId
* Added server/logging.ts
- Initialize logsUpdateIntervals to Map session ID to the interval for sending logging messages to the client
- in beginSimulatedLogging()
- create an array of logging meesages, customized with the sessionId if present
- if the interval for the sessionId hasn't been set, create one, calling server.sendLoggingMessage with a random message to the client each time the interval elapses
- in stopSimulatedLogging()
- if a logging interval exists for the sessionId, clear it and remove it
* In subscriptions.ts
- remove import of Transport
- remove transports map
- in beginSimulatedResourceUpdates()
- change arguments to server and sessionId
- check for the subsUpdateInterval for the session
- remove all transport storage and interaction
- instead use the server to send the notification
- in stopSimulatedResourceUpdates()
- remove management of transports map
* In sse.ts and streamableHttp.ts
- when calling clientConnected, pass sessionId instead of transport
* In stdio.ts,
- when calling clientConnected, pass nothing instead of transport
* In subscriptions.ts
- updated inline doc
Adding resource subscriptions:
* Updated architecture.md
* In server/index.ts
- imported Transport, setSubscriptionHandlers,beginSimulatedResourceUpdates, and stopSimulatedResourceUpdates
- call setSubscriptionHandlers passing server
- in returned object,
- refactor/renamed startNotificationIntervals placehodler to clientConnected, which takes a transport argument and calls beginSimulatedResourceUpdates, passing the transport
- replaced cleanup placeholder with a function that takes an optional sessionId and calls stopSimulatedResourceUpdates, passing the sessionId
* In sse.ts, stdio.ts, and streamableHttp.ts
- when transport is connected, called clientConnect, passing transport
- when disconnecting, called cleanup, passing sessionId
* Added subscriptions.ts
- tracks subscriber session id lists by URI
- tracks transport by session id
- tracks subscription update intervals by sessionId
- in setSubscriptionHandlers
- set request handlers for SubscribeRequestSchema and UnsubscribeRequestSchema
- in beginSimulatedResourceUpdates
- starts an interval to send updates to the transport for all subscribed resources
- in stopSimulatedResourceUpdates
- removes intervals and transport for gien session id
* Updated architecture.md
* Refactor/renamed static.ts to file.ts
* Refactor/renamed complex.ts to args.ts
* Refactor/renamed template.ts to templates.ts.
* In resource.ts,
- improved registerEmbeddedResourcePrompt to allow selection of blob or text resource type.
* In file.ts
- refactor/renamed registerStaticResources to registerFileResources to highlight the fact that it is using files as resources.
* In args.ts
- refactor/renamed registerComplexPrompt to registerArgumentsPrompt to highlight the fact that it is demonstrating prompt arguments.
* Updated inline documentation throughout
* Updated architecture.md
* Refactor/renamed resources/dynamic.ts to resources/template.ts
- refactor/renamed registerDynamicResources to registerResourceTemplates
- this highlights the more salient fact that we are demonstrating registration of resource templates in this example.
- exposed the ability to dynamically create the text resources from elsewhere (namely the resource-prompt example
* Added prompts/resource.ts
- in registerEmbeddedResourcePrompt()
- register a prompt that takes a resourceId and returns the prompt with the corresponding dynamically created resource embedded
* Adding prompts (simple, complex, with completions)
* Add prompts/simple.ts
- in addSimplePrompt()
- register a simple prompt with no arguments
* Add prompts/complex.ts
- in addComplexPrompt()
- define promptArgsSchema containing a required city arg of type string and an optional state arg of type state
- register the complex prompt with a prompt callback that combines the city and state into a prompt asking for the weather in that location
* Add prompts/completions.ts
- in addPromptWithCompletions()
- define promptArgsSchema containing department and name string fields with completion handlers
- register the completable prompt with a prompt callback that combines the inputs into a prompt asking to promote the selected name to head of the selected department
* Add prompts/index.ts
- import addSimplePrompt, addComplexPrompt, and addPromptWithCompletions
- export registerPrompts function
- in registerPrompts()
- call addSimplePrompt
- call addComplexPrompt
- call addPromptWithCompletions
* In package.json
- add prettier devDependency
- add prettier:check script
- add prettier:fix script
- in build script, copy docs folder to dist
* All other changes were prettier formatting
* Adding static resources, move server instructions to
the new docs folder, and add code formatting
* Add docs folder
* Add docs/architecture.md which describes the architecture of the project thus far.
* Refactor moved instructions.md to docs/server-instructions.md
* Add resources/static.ts
- in addStaticResources()
- read the file entries from the docs folder
- register each file as a resource (no template), with a readResource function that reads the file and returns it in a contents block with the appropriate mime type and contents
- getMimeType helper function gets the mime type for a filename
- readSafe helper function reads the file synchronously as utf-8 or returns an error string
* Add resources/index.ts
- import addStaticResources
- export registerResources function
- in registerResources()
- call addStaticResources
* In package.json
- add prettier devDependency
- add prettier:check script
- add prettier:fix script
- in build script, copy docs folder to dist
* All other changes were prettier formatting
* Adding dynamic resources
* Add server/index.js
- import registerResources from resources/index.js
- in createServer()
- call registerResources, passing server
* Add resources/dynamic.ts
- in addDynamicResources()
- define formatGmtTimestamp to create a time stamp to include in the resource text or encoded blob
- define parseIndex to ensure the index variable of the URI is a number
* Add resources/index.ts
- import addDynamicResources
- export registerResources function
- in registerResources()
- call addDynamicResources
* In package.json
- update the start commands to launch each of the transports properly
In src/everything:
* Refactor / move streamableHttp.ts, sse.ts, and stdio.ts to transports/
* Move everything.ts to server/ for reference
* Add server/index.js
- exports the createServer function
- import registerTools from tools/index.js
- in createServer()
- read instructions.md and include in ServerOptions for McpServer constructor
- construct McpServer instead of Server
- call registerTools, passing server
* Add tools/echo.ts
- define EchoSchema
- define tool config
- export addToolEcho function
- in addToolEcho()
- register handler for Echo tool
* Add tools/index.ts
- import addToolEcho
- export registerTools function
- in registerTools()
- call addToolEcho
Fixes issue where relative paths were incorrectly resolved against process.cwd(),
causing "Access denied - path outside allowed directories" errors when the MCP
server's working directory was outside the configured allowed directories.
The fix implements intelligent path resolution that:
1. First tries to resolve relative paths against each allowed directory
2. Validates the resulting path is within allowed directories
3. Falls back to the first allowed directory if no valid resolution is found
4. Maintains backward compatibility by falling back to process.cwd() when no allowed directories are configured
Resolves#2526🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Ola Hungerford <olaservo@users.noreply.github.com>
2025-08-24 02:44:31 +00:00
126 changed files with 14208 additions and 5830 deletions
'**We are no longer accepting PRs to add new servers to the README.** The third-party server list has been removed from this README in favor of the [MCP Server Registry](https://registry.modelcontextprotocol.io/).',
'',
'👉 **To add a new MCP server:** Please publish it to the [MCP Server Registry](https://github.com/modelcontextprotocol/registry) instead. You can browse published servers at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/).',
'',
'👉 **If this PR updates or removes an existing entry:** We do still accept these changes. Please reply with `/i-promise-this-is-not-a-new-server` to continue.',
'',
'If this PR is adding a new server, please close it and submit to the registry instead.',
This is a curated collection of community-built frameworks and resources that simplify building MCP servers and clients, along with other useful tools, libraries, and references for working with MCP.
## 📚 Frameworks
### For servers
* **[Anubis MCP](https://github.com/zoedsoupe/anubis-mcp)** (Elixir) - A high-performance and high-level Model Context Protocol (MCP) implementation in Elixir. Think like "Live View" for MCP.
* **[ModelFetch](https://github.com/phuctm97/modelfetch/)** (TypeScript) - Runtime-agnostic SDK to create and deploy MCP servers anywhere TypeScript/JavaScript runs
* **[FastAPI to MCP auto generator](https://github.com/tadata-org/fastapi_mcp)** – A zero-configuration tool for automatically exposing FastAPI endpoints as MCP tools by **[Tadata](https://tadata.com/)**
* **[Foobara MCP Connector](https://github.com/foobara/mcp-connector)** - Easily expose Foobara commands written in Ruby as tools via MCP
* **[Foxy Contexts](https://github.com/strowk/foxy-contexts)** – A library to build MCP servers in Golang by **[strowk](https://github.com/strowk)**
* **[Higress MCP Server Hosting](https://github.com/alibaba/higress/tree/main/plugins/wasm-go/mcp-servers)** - A solution for hosting MCP Servers by extending the API Gateway (based on Envoy) with wasm plugins.
* **[MCP Declarative Java SDK](https://github.com/codeboyzhou/mcp-declarative-java-sdk)** Annotation-driven MCP servers development with Java, no Spring Framework Required, minimize dependencies as much as possible.
* **[MCP-Framework](https://mcp-framework.com)** Build MCP servers with elegance and speed in TypeScript. Comes with a CLI to create your project with `mcp create app`. Get started with your first server in under 5 minutes by **[Alex Andru](https://github.com/QuantGeekDev)**
* **[MCP Plexus](https://github.com/Super-I-Tech/mcp_plexus)**: A secure, **multi-tenant** and Multi-user MCP python server framework built to integrate easily with external services via OAuth 2.1, offering scalable and robust solutions for managing complex AI applications.
* **[mcp_sse (Elixir)](https://github.com/kEND/mcp_sse)** An SSE implementation in Elixir for rapidly creating MCP servers.
* **[mxcp](https://github.com/raw-labs/mxcp)** (Python) - Open-source framework for building enterprise-grade MCP servers using just YAML, SQL, and Python, with built-in auth, monitoring, ETL and policy enforcement.
* **[Next.js MCP Server Template](https://github.com/vercel-labs/mcp-for-next.js)** (Typescript) - A starter Next.js project that uses the MCP Adapter to allow MCP clients to connect and access resources.
* **[PayMCP](https://github.com/blustAI/paymcp)** (Python & TypeScript) - Lightweight payments layer for MCP servers: turn tools into paid endpoints with a two-line decorator. [PyPI](https://pypi.org/project/paymcp/) · [npm](https://www.npmjs.com/package/paymcp) · [TS repo](https://github.com/blustAI/paymcp-ts)
* **[Perl SDK](https://github.com/mojolicious/mojo-mcp)** - An SDK for building MCP servers and clients with the Perl programming language.
* **[Quarkus MCP Server SDK](https://github.com/quarkiverse/quarkus-mcp-server)** (Java)
- **[R mcptools](https://github.com/posit-dev/mcptools)** - An R SDK for creating R-based MCP servers and retrieving functionality from third-party MCP servers as R functions.
* **[SAP ABAP MCP Server SDK](https://github.com/abap-ai/mcp)** - Build SAP ABAP based MCP servers. ABAP 7.52 based with 7.02 downport; runs on R/3 & S/4HANA on-premises, currently not cloud-ready.
* **[Spring AI MCP Server](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html)** - Provides auto-configuration for setting up an MCP server in Spring Boot applications.
* **[Template MCP Server](https://github.com/mcpdotdirect/template-mcp-server)** - A CLI tool to create a new Model Context Protocol server project with TypeScript support, dual transport options, and an extensible structure
* **[AgentR Universal MCP SDK](https://github.com/universal-mcp/universal-mcp)** - A python SDK to build MCP Servers with inbuilt credential management by **[Agentr](https://agentr.dev/home)**
* **[Vercel MCP Adapter](https://github.com/vercel/mcp-adapter)** (TypeScript) - A simple package to start serving an MCP server on most major JS meta-frameworks including Next, Nuxt, Svelte, and more.
* **[PHP MCP Server](https://github.com/php-mcp/server)** (PHP) - Core PHP implementation for the Model Context Protocol (MCP) server
### For clients
* **[codemirror-mcp](https://github.com/marimo-team/codemirror-mcp)** - CodeMirror extension that implements the Model Context Protocol (MCP) for resource mentions and prompt commands
* **[llm-analysis-assistant](https://github.com/xuzexin-hz/llm-analysis-assistant)** <img height="12" width="12" src="https://raw.githubusercontent.com/xuzexin-hz/llm-analysis-assistant/refs/heads/main/src/llm_analysis_assistant/pages/html/imgs/favicon.ico" alt="Langfuse Logo" /> - A very streamlined mcp client that supports calling and monitoring stdio/sse/streamableHttp, and can also view request responses through the /logs page. It also supports monitoring and simulation of ollama/openai interface.
* **[MCP-Agent](https://github.com/lastmile-ai/mcp-agent)** - A simple, composable framework to build agents using Model Context Protocol by **[LastMile AI](https://www.lastmileai.dev)**
* **[Spring AI MCP Client](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html)** - Provides auto-configuration for MCP client functionality in Spring Boot applications.
* **[MCP CLI Client](https://github.com/vincent-pli/mcp-cli-host)** - A CLI host application that enables Large Language Models (LLMs) to interact with external tools through the Model Context Protocol (MCP).
* **[OpenMCP Client](https://github.com/LSTM-Kirigaya/openmcp-client/)** - An all-in-one vscode/trae/cursor plugin for MCP server debugging. [Document](https://kirigaya.cn/openmcp/) & [OpenMCP SDK](https://kirigaya.cn/openmcp/sdk-tutorial/).
* **[PHP MCP Client](https://github.com/php-mcp/client)** - Core PHP implementation for the Model Context Protocol (MCP) Client
* **[Runbear](https://runbear.io/solutions/integrations/slack/mcp)** - No-code MCP client for team chat platforms, such as Slack, Microsoft Teams, and Discord.
## 📚 Resources
- **[A2A-MCP Java Bridge](https://github.com/vishalmysore/a2ajava)** - A2AJava brings powerful A2A-MCP integration directly into your Java applications. It enables developers to annotate standard Java methods and instantly expose them as MCP Server, A2A-discoverable actions — with no boilerplate or service registration overhead.
- **[AiMCP](https://www.aimcp.info)** - A collection of MCP clients&servers to find the right mcp tools by **[Hekmon](https://github.com/hekmon8)**
- **[Awesome Crypto MCP Servers by badkk](https://github.com/badkk/awesome-crypto-mcp-servers)** - A curated list of MCP servers by **[Luke Fan](https://github.com/badkk)**
- **[Awesome MCP Servers by appcypher](https://github.com/appcypher/awesome-mcp-servers)** - A curated list of MCP servers by **[Stephen Akinyemi](https://github.com/appcypher)**
- **[Awesome MCP Servers by punkpeye](https://github.com/punkpeye/awesome-mcp-servers)** (**[website](https://glama.ai/mcp/servers)**) - A curated list of MCP servers by **[Frank Fiegel](https://github.com/punkpeye)**
- **[Awesome MCP Servers by wong2](https://github.com/wong2/awesome-mcp-servers)** (**[website](https://mcpservers.org)**) - A curated list of MCP servers by **[wong2](https://github.com/wong2)**
- **[Awesome Remote MCP Servers by JAW9C](https://github.com/jaw9c/awesome-remote-mcp-servers)** - A curated list of **remote** MCP servers, including their authentication support by **[JAW9C](https://github.com/jaw9c)**
- **[Discord Server](https://glama.ai/mcp/discord)** – A community discord server dedicated to MCP by **[Frank Fiegel](https://github.com/punkpeye)**
- **[Install This MCP](https://installthismcp.com)** - Reduce Installation Friction with beautiful installation guides
- **[Klavis AI](https://www.klavis.ai)** - Open Source MCP Infra. Hosted MCP servers and MCP clients on Slack and Discord.
- **[MCP Badges](https://github.com/mcpx-dev/mcp-badges)** – Quickly highlight your MCP project with clear, eye-catching badges, by **[Ironben](https://github.com/nanbingxyz)**
- **[MCPProxy](https://github.com/smart-mcp-proxy/mcpproxy-go)** - Open-source local app that enables access to multiple MCP servers and thousands of tools with intelligent discovery via MCP protocol, runs servers in isolated environments, and features automatic quarantine protection against malicious tools.
- **[MCPRepository.com](https://mcprepository.com/)** - A repository that indexes and organizes all MCP servers for easy discovery.
- **[mcp-cli](https://github.com/wong2/mcp-cli)** - A CLI inspector for the Model Context Protocol by **[wong2](https://github.com/wong2)**
- **[mcp-dockmaster](https://mcp-dockmaster.com)** - An Open-Sourced UI to install and manage MCP servers for Windows, Linux and macOS.
- **[mcp-get](https://mcp-get.com)** - Command line tool for installing and managing MCP servers by **[Michael Latman](https://github.com/michaellatman)**
- **[mcp-guardian](https://github.com/eqtylab/mcp-guardian)** - GUI application + tools for proxying / managing control of MCP servers by **[EQTY Lab](https://eqtylab.io)**
- **[MCP Linker](https://github.com/milisp/mcp-linker)** - A cross-platform Tauri GUI tool for one-click setup and management of MCP servers, supporting Claude Desktop, Cursor, Windsurf, VS Code, Cline, and Neovim.
- **[mcp-manager](https://github.com/zueai/mcp-manager)** - Simple Web UI to install and manage MCP servers for Claude Desktop by **[Zue](https://github.com/zueai)**
- **[MCP Marketplace Web Plugin](https://github.com/AI-Agent-Hub/mcp-marketplace)** MCP Marketplace is a small Web UX plugin to integrate with AI applications, Support various MCP Server API Endpoint (e.g pulsemcp.com/deepnlp.org and more). Allowing user to browse, paginate and select various MCP servers by different categories. [Pypi](https://pypi.org/project/mcp-marketplace) | [Maintainer](https://github.com/AI-Agent-Hub) | [Website](http://www.deepnlp.org/store/ai-agent/mcp-server)
- **[mcp.natoma.ai](https://mcp.natoma.ai)** – A Hosted MCP Platform to discover, install, manage and deploy MCP servers by **[Natoma Labs](https://www.natoma.ai)**
- **[mcp.run](https://mcp.run)** - A hosted registry and control plane to install & run secure + portable MCP Servers.
- **[MCPHub](https://www.mcphub.com)** - Website to list high quality MCP servers and reviews by real users. Also provide online chatbot for popular LLM models with MCP server support.
- **[MCP Router](https://mcp-router.net)** – Free Windows and macOS app that simplifies MCP management while providing seamless app authentication and powerful log visualization by **[MCP Router](https://github.com/mcp-router/mcp-router)**
- **[MCP Servers Hub](https://github.com/apappascs/mcp-servers-hub)** (**[website](https://mcp-servers-hub-website.pages.dev/)**) - A curated list of MCP servers by **[apappascs](https://github.com/apappascs)**
- **[MCPServers.com](https://mcpservers.com)** - A growing directory of high-quality MCP servers with clear setup guides for a variety of MCP clients. Built by the team behind the **[Highlight MCP client](https://highlightai.com/)**
- **[MCP Servers Rating and User Reviews](http://www.deepnlp.org/store/ai-agent/mcp-server)** - Website to rate MCP servers, write authentic user reviews, and [search engine for agent & mcp](http://www.deepnlp.org/search/agent)
- **[MCP Sky](https://bsky.app/profile/brianell.in/feed/mcp)** - Bluesky feed for MCP related news and discussion by **[@brianell.in](https://bsky.app/profile/brianell.in)**
- **[MCP X Community](https://x.com/i/communities/1861891349609603310)** – A X community for MCP by **[Xiaoyi](https://x.com/chxy)**
- **[MCPHub](https://github.com/Jeamee/MCPHub-Desktop)** – An Open Source macOS & Windows GUI Desktop app for discovering, installing and managing MCP servers by **[Jeamee](https://github.com/jeamee)**
- **[mcpm](https://github.com/pathintegral-institute/mcpm.sh)** ([website](https://mcpm.sh)) - MCP Manager (MCPM) is a Homebrew-like service for managing Model Context Protocol (MCP) servers across clients by **[Pathintegral](https://github.com/pathintegral-institute)**
- **[MCPVerse](https://mcpverse.dev)** - A portal for creating & hosting authenticated MCP servers and connecting to them securely.
- **[MCP Servers Search](https://github.com/atonomus/mcp-servers-search)** - An MCP server that provides tools for querying and discovering available MCP servers from this list.
- **[Search MCP Server](https://github.com/krzysztofkucmierz/search-mcp-server)** - Recommends the most relevant MCP servers based on the client's query by searching this README file.
- **[MCPWatch](https://github.com/kapilduraphe/mcp-watch)** - A comprehensive security scanner for Model Context Protocol (MCP) servers that detects vulnerabilities and security issues in your MCP server implementations.
- **[mkinf](https://mkinf.io)** - An Open Source registry of hosted MCP Servers to accelerate AI agent workflows.
- **[Open-Sourced MCP Servers Directory](https://github.com/chatmcp/mcp-directory)** - A curated list of MCP servers by **[mcpso](https://mcp.so)**
- **[OpenTools](https://opentools.com)** - An open registry for finding, installing, and building with MCP servers by **[opentoolsteam](https://github.com/opentoolsteam)**
- **[Programmatic MCP Prototype](https://github.com/domdomegg/programmatic-mcp-prototype)** - Experimental agent prototype demonstrating programmatic MCP tool composition, progressive tool discovery, state persistence, and skill building through TypeScript code execution by **[Adam Jones](https://github.com/domdomegg)**
- **[PulseMCP](https://www.pulsemcp.com)** ([API](https://www.pulsemcp.com/api)) - Community hub & weekly newsletter for discovering MCP servers, clients, articles, and news by **[Tadas Antanavicius](https://github.com/tadasant)**, **[Mike Coughlin](https://github.com/macoughl)**, and **[Ravina Patel](https://github.com/ravinahp)**
- **[r/mcp](https://www.reddit.com/r/mcp)** – A Reddit community dedicated to MCP by **[Frank Fiegel](https://github.com/punkpeye)**
- **[MCP.ing](https://mcp.ing/)** - A list of MCP services for discovering MCP servers in the community and providing a convenient search function for MCP services by **[iiiusky](https://github.com/iiiusky)**
- **[MCP Hunt](https://mcp-hunt.com)** - Realtime platform for discovering trending MCP servers with momentum tracking, upvoting, and community discussions - like Product Hunt meets Reddit for MCP
- **[Smithery](https://smithery.ai/)** - A registry of MCP servers to find the right tools for your LLM agents by **[Henry Mao](https://github.com/calclavia)**
- **[Toolbase](https://gettoolbase.ai)** - Desktop application that manages tools and MCP servers with just a few clicks - no coding required by **[gching](https://github.com/gching)**
- **[ToolHive](https://github.com/StacklokLabs/toolhive)** - A lightweight utility designed to simplify the deployment and management of MCP servers, ensuring ease of use, consistency, and security through containerization by **[StacklokLabs](https://github.com/StacklokLabs)**
- **[NetMind](https://www.netmind.ai/AIServices)** - Access powerful AI services via simple APIs or MCP servers to supercharge your productivity.
- **[Webrix MCP Gateway](https://github.com/webrix-ai/secure-mcp-gateway)** - Enterprise MCP gateway with SSO, RBAC, audit trails, and token vaults for secure, centralized AI agent access control. Deploy via Helm charts on-premise or in your cloud. [webrix.ai](https://webrix.ai)
This file provides guidance to Claude Code when working with code in this repository.
## Project Overview
Official MCP reference server implementations. This is an npm workspaces monorepo containing 7 servers (4 TypeScript, 3 Python) under `src/`. Each server is a standalone package published to npm or PyPI.
## Monorepo Structure
```
src/
everything/ TS @modelcontextprotocol/server-everything (reference server, all MCP features)
filesystem/ TS @modelcontextprotocol/server-filesystem (file operations with Roots access control)
- Strict TypeScript typing for all functions and variables
- Zod schemas for tool input validation
- 2-space indentation, trailing commas in multi-line objects
- camelCase for variables/functions, PascalCase for types/classes, UPPER_CASE for constants
- kebab-case for file names and registered tools/prompts/resources
- Verb-first tool names (e.g., `get-file-info`, not `file-info`)
- Imports grouped: external first, then internal
### Python
- Type hints enforced via pyright
- Async/await patterns (especially in fetch server with pytest-asyncio)
- Follow existing module layout per server
## Contributing Guidelines
**Accepted:** Bug fixes, usability improvements, enhancements demonstrating MCP protocol features (Resources, Prompts, Roots -- not just Tools).
**Selective:** New features outside a server's core purpose or highly opinionated additions.
**Not accepted:** New server implementations (use the [MCP Server Registry](https://github.com/modelcontextprotocol/registry)), README server listing changes.
## CI/CD Pipeline
Both TypeScript and Python workflows use **dynamic package detection** (find + jq matrix strategy):
1. `detect-packages` -- finds all `package.json` / `pyproject.toml` under `src/`
2. `test` -- runs tests per package
3. `build` -- compiles and type-checks per package
4. `publish` -- on release events only (npm for TS, PyPI trusted publishing for Python)
## MCP Protocol Reference
The repo is configured with an MCP docs server (`.mcp.json`) pointing to `https://modelcontextprotocol.io/mcp`. For schema details, reference `https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/schema` which contains versioned schemas in JSON and TypeScript formats.
## Key Patterns
- Each server registers capabilities via `registerTools(server)`, `registerResources(server)`, `registerPrompts(server)` functions
- Tool annotations: set `readOnlyHint`, `idempotentHint`, `destructiveHint` per MCP spec
- Transport support: stdio (default), SSE (deprecated), Streamable HTTP
- All PRs are reviewed against the [PR template](.github/pull_request_template.md) checklist -- ensure MCP docs are read, security best practices followed, and changes tested with an LLM client
@ -6,9 +6,9 @@ We accept changes through [the standard GitHub flow model](https://docs.github.c
## Server Listings
## Server Listings
We are **no longer accepting PRs** to add server links to the README. Please publish your server to the [MCP Server Registry](https://github.com/modelcontextprotocol/registry) instead. Follow the [quickstart guide](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx).
The README no longer contains a list of third-party MCP servers — that list has been retired in favor of the [MCP Server Registry](https://github.com/modelcontextprotocol/registry). To make your server discoverable, follow the [quickstart guide](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx) to publish it there.
You can browse published servers using the simple UI at [https://registry.modelcontextprotocol.io/](https://registry.modelcontextprotocol.io/).
You can browse published servers at [https://registry.modelcontextprotocol.io/](https://registry.modelcontextprotocol.io/).
The MCP project is undergoing a licensing transition from the MIT License to the Apache License, Version 2.0 ("Apache-2.0"). All new code and specification contributions to the project are licensed under Apache-2.0. Documentation contributions (excluding specifications) are licensed under CC-BY-4.0.
Contributions for which relicensing consent has been obtained are licensed under Apache-2.0. Contributions made by authors who originally licensed their work under the MIT License and who have not yet granted explicit permission to relicense remain licensed under the MIT License.
No rights beyond those granted by the applicable original license are conveyed for such contributions.
---
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to the Licensor for inclusion in the Work by the copyright
owner or by an individual or Legal Entity authorized to submit on behalf
of the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
How the packages in this repository are published, and what to do when a publish fails.
## How publishing works
All packages publish exclusively from the [`release.yml`](.github/workflows/release.yml) GitHub Actions workflow, gated by the `release` environment (a required reviewer must approve each deployment). Releases are triggered deliberately by a maintainer via **workflow_dispatch** (Actions → Release → Run workflow, or `gh workflow run release.yml`) — there is no scheduled/automatic release.
**Authentication is OIDC trusted publishing on both registries — there are no registry tokens.**
- **npm** (TypeScript servers): each `@modelcontextprotocol/*` package is registered on npmjs.com with a [trusted publisher](https://docs.npmjs.com/trusted-publishers) bound to this repository, workflow filename `release.yml`, and environment `release` (the binding is case-sensitive). Packages publish with [provenance attestations](https://docs.npmjs.com/generating-provenance-statements).
- **PyPI** (Python servers): published via [PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) using `pypa/gh-action-pypi-publish`.
A release run:
1. **Detects changed packages** since the last release tag — a package counts as changed if any `.py`, `.ts`, or `.md` file in its directory changed (READMEs ship inside the published artifacts).
2. **Stamps versions and pushes the release tag** — versions are date-based (CalVer, e.g. `2026.7.4`).
3. **Publishes each changed package as an independent matrix job** (`fail-fast: false` — one package's failure never blocks another). Each job: checkout at the release tag → install → double-publish guard → **run the package's tests** (plus `pyright` for Python) → build → publish. The guard differs by registry: the npm job aborts before tests if the version already exists; for PyPI the skip happens at the publish step itself (`skip-existing` on the upload action).
4. **Creates the GitHub release** with generated notes.
## When a publish fails
A failed matrix leg means that one package didn't publish; everything that succeeded stays published.
**Preferred: re-run the failed jobs on the same run.**
```bash
gh run rerun <run-id> --failed --repo modelcontextprotocol/servers
```
- A re-run is still a `release.yml` run in the `release` environment, so it satisfies the trusted-publisher binding.
- It re-runs only the failed legs, checked out at the original release tag — it publishes exactly the tagged code, and the double-publish guard keeps already-published packages safe.
- It needs a fresh `release` environment approval, and the run must be complete first (approve or reject any pending deployments).
- GitHub's re-run window is ~30 days from the original run, and re-runs execute the *original* workflow snapshot — workflow fixes on `main` don't apply to a re-run.
**Otherwise: let the next release pick it up.** If the re-run window has closed (or the fix required a workflow change), the failed version simply never exists on that registry — that's benign; npm and PyPI version histories don't need to match. The package publishes at the next version, provided it has a qualifying change (`.py`, `.ts`, or `.md`) since the last release tag.
**Never:**
- Publish manually with an npm token or from a laptop — there are no registry tokens, and manual publishes would break the provenance/trust chain.
- Dispatch a fresh `release.yml` run expecting it to retry a failed version — versions are date-granular, so a same-day dispatch collides with the existing tag, and a later dispatch mints a *new* version. Neither retries the failed one.
## Environment approvals
The `release` environment's required-reviewer list is configured in the repository settings (Settings → Environments → `release`). Reviewer rights come only from that list — repository admin does not confer deployment approval.
---
Planned changes to this process — semver via changesets for the TypeScript packages, publishing triggered by manually-created GitHub Releases — are tracked in [#4463](https://github.com/modelcontextprotocol/servers/issues/4463). This document will be updated when that work merges.
Thank you for helping us keep our MCP servers secure.
The **reference servers** in this repo are maintained by [Anthropic](https://www.anthropic.com/) as part of the Model Context Protocol project.
Thank you for helping keep the Model Context Protocol and its ecosystem secure.
The security of our systems and user data is Anthropic’s top priority. We appreciate the work of security researchers acting in good faith in identifying and reporting potential vulnerabilities.
## Important Notice
## Vulnerability Disclosure Program
The servers in this repository are **reference implementations** intended to demonstrate
MCP features and SDK usage. They serve as educational examples for developers building
their own MCP servers, not as production-ready solutions.
Our Vulnerability Program guidelines are defined on our [HackerOne program page](https://hackerone.com/anthropic-vdp). We ask that any validated vulnerability in this functionality be reported through the [submission form](https://hackerone.com/anthropic-vdp/reports/new?type=team&report_type=vulnerability).
This repository is **not** eligible for security vulnerability reporting. If you discover
a vulnerability in an MCP SDK, please report it in the appropriate SDK repository.
## Reporting Security Issues in MCP SDKs
If you discover a security vulnerability in an MCP SDK, please report it through the
This MCP server attempts to exercise all the features of the MCP protocol. It is not intended to be a useful server, but rather a test server for builders of MCP clients. It implements prompts, tools, resources, sampling, and more to showcase MCP capabilities.
This MCP server attempts to exercise all the features of the MCP protocol. It is not intended to be a useful server, but rather a test server for builders of MCP clients. It implements prompts, tools, resources, sampling, and more to showcase MCP capabilities.
## Components
## Tools, Resources, Prompts, and Other Features
### Tools
A complete list of the registered MCP primitives and other protocol features demonstrated can be found in the [Server Features](docs/features.md) document.
1. `echo`
- Simple tool to echo back input messages
- Input:
- `message` (string): Message to echo back
- Returns: Text content with echoed message
2. `add`
- Adds two numbers together
- Inputs:
- `a` (number): First number
- `b` (number): Second number
- Returns: Text result of the addition
3. `longRunningOperation`
- Demonstrates progress notifications for long operations
- Inputs:
- `duration` (number, default: 10): Duration in seconds
- `steps` (number, default: 5): Number of progress steps
- Returns: Completion message with duration and steps
- Sends progress notifications during execution
4. `printEnv`
- Prints all environment variables
- Useful for debugging MCP server configuration
- No inputs required
- Returns: JSON string of all environment variables
5. `sampleLLM`
- Demonstrates LLM sampling capability using MCP sampling feature
- Inputs:
- `prompt` (string): The prompt to send to the LLM
- `maxTokens` (number, default: 100): Maximum tokens to generate
- Returns: Generated LLM response
6. `getTinyImage`
- Returns a small test image
- No inputs required
- Returns: Base64 encoded PNG image data
7. `annotatedMessage`
- Demonstrates how annotations can be used to provide metadata about content
- Inputs:
- `messageType` (enum: "error" | "success" | "debug"): Type of message to demonstrate different annotation patterns
- `includeImage` (boolean, default: false): Whether to include an example image
- Returns: Content with varying annotations:
- Error messages: High priority (1.0), visible to both user and assistant
- Success messages: Medium priority (0.7), user-focused
- Optional image: Medium priority (0.5), user-focused
- Example annotations:
```json
{
"priority": 1.0,
"audience": ["user", "assistant"]
}
```
8. `getResourceReference`
- Returns a resource reference that can be used by MCP clients
- Inputs:
- `resourceId` (number, 1-100): ID of the resource to reference
- Returns: A resource reference with:
- Text introduction
- Embedded resource with `type: "resource"`
- Text instruction for using the resource URI
9. `startElicitation`
- Initiates an elicitation (interaction) within the MCP client.
- Inputs:
- `color` (string): Favorite color
- `number` (number, 1-100): Favorite number
- `pets` (enum): Favorite pet
- Returns: Confirmation of the elicitation demo with selection summary.
10. `structuredContent`
- Demonstrates a tool returning structured content using the example in the specification
- Provides an output schema to allow testing of client SHOULD advisory to validate the result using the schema
- Inputs:
- `location` (string): A location or ZIP code, mock data is returned regardless of value
- Returns: a response with
- `structuredContent` field conformant to the output schema
- A backward compatible Text Content field, a SHOULD advisory in the specification
11. `listRoots`
- Lists the current MCP roots provided by the client
- Demonstrates the roots protocol capability even though this server doesn't access files
- No inputs required
- Returns: List of current roots with their URIs and names, or a message if no roots are set
- Shows how servers can interact with the MCP roots protocol
### Resources
The server provides 100 test resources in two formats:
- Even numbered resources:
- Plaintext format
- URI pattern: `test://static/resource/{even_number}`
- Content: Simple text description
- Odd numbered resources:
- Binary blob format
- URI pattern: `test://static/resource/{odd_number}`
- Content: Base64 encoded binary data
Resource features:
- Supports pagination (10 items per page)
- Allows subscribing to resource updates
- Demonstrates resource templates
- Auto-updates subscribed resources every 5 seconds
### Prompts
1. `simple_prompt`
- Basic prompt without arguments
- Returns: Single message exchange
2. `complex_prompt`
- Advanced prompt demonstrating argument handling
- Required arguments:
- `temperature` (string): Temperature setting
- Optional arguments:
- `style` (string): Output style preference
- Returns: Multi-turn conversation with images
3. `resource_prompt`
- Demonstrates embedding resource references in prompts
- Required arguments:
- `resourceId` (number): ID of the resource to embed (1-100)
- Returns: Multi-turn conversation with an embedded resource reference
- Shows how to include resources directly in prompt messages
### Roots
The server demonstrates the MCP roots protocol capability:
- Declares `roots: { listChanged: true }` capability to indicate support for roots
- Handles `roots/list_changed` notifications from clients
- Requests initial roots during server initialization
- Provides a `listRoots` tool to display current roots
- Logs roots-related events for demonstration purposes
Note: This server doesn't actually access files, but demonstrates how servers can interact with the roots protocol for clients that need to understand which directories are available for file operations.
### Logging
The server sends random-leveled log messages every 15 seconds, e.g.:
```json
{
"method": "notifications/message",
"params": {
"level": "info",
"data": "Info-level message"
}
}
```
## Usage with Claude Desktop (uses [stdio Transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#stdio))
## Usage with Claude Desktop (uses [stdio Transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#stdio))
@ -180,9 +31,27 @@ Add to your `claude_desktop_config.json`:
}
}
```
```
On Windows, use `cmd /c` to launch `npx`:
```json
{
"mcpServers": {
"everything": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@modelcontextprotocol/server-everything"
]
}
}
}
```
## Usage with VS Code
## Usage with VS Code
For quick installation, use of of the one-click install buttons below...
For quick installation, use one of the one-click install buttons below...
[](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-everything%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-everything%22%5D%7D&quality=insiders)
[](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-everything%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-everything%22%5D%7D&quality=insiders)
@ -211,6 +80,19 @@ Alternatively, you can add the configuration to a file called `.vscode/mcp.json`
## Running from source with [HTTP+SSE Transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse) (deprecated as of [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports))
## Running from source with [HTTP+SSE Transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse) (deprecated as of [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports))
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
Some files were not shown because too many files have changed in this diff
Show more
