npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@pegma/knowledge-base-mcp

v0.1.8

Published

Optional MCP transport for authorized Pegma knowledge authoring and validation.

Readme

@pegma/knowledge-base-mcp

Optional KB-04 agent transport source for Pegma Knowledge Base. This package adapts the authorized application API to bounded agent commands and the Model Context Protocol. Hosts compose it with their protected Knowledge Base endpoints; the package does not supply a hosted service.

The historical synchronized 0.1.5 release includes answering read batching and the aggregate report query introduced in 0.1.4. The current verified synchronized release is 0.1.7, described below. Changed source requires its own review and current-head gates. Host and actual client acceptance remain separate. These source README corrections apply to a future release. Published 0.1.5 tarballs, including their bundled README bytes, remain unchanged.

The verified 0.1.6 release accepts bounded opaque MCP params._meta extensions, including native-client correlation and standard trace fields, while retaining the existing progressToken shape validation: a string of at most 128 characters or a safe integer. Metadata does not establish identity, permissions or evidence and is not stored or returned as an application result. Complete-message byte, depth, node and key ceilings, strict tool arguments and fresh host authentication remain unchanged. The official-SDK regression and packed protocol proof exercise fictional extension values; actual requested-client and host acceptance remain separate.

The verified 0.1.7 release synchronizes all four packages for the staff report receipt extension. The unpublished 0.1.8 candidate adds an application-only report observation pair; the five MCP tools and three scopes remain unchanged.

The contracts, core, and application packages remain independent of MCP, HTTP, provider SDKs, and login flows. Hosts choose this adapter when exposing agent access. The adapter pins @modelcontextprotocol/sdk at 1.32.2 and zod at 4.6.7; it composes the matching exact Knowledge Base package versions declared in its dependencies.

The MCP adapter explicitly uses the SDK's Workers-compatible JSON Schema validator, which requires no generated code. Its @cfworker/json-schema dependency is pinned at 4.1.6 and required by this package even though the SDK declares it as an optional peer. Packed consumers receive the validator without needing to discover or install that peer themselves.

Trust and composition

The host owns credential issuance, authentication, resource binding, current authorization, and evidence verification. Compose the adapter with the Knowledge Base application and host authentication ports. Agent Access is a separate producer; it is not a runtime dependency of this package. An opaque credential, caller-supplied actor, or claimed evidence result does not establish an authenticated AccessContext or trusted evidence.

Agent operations use the same current-resource authorization, application generation, immutable evidence, replay, and publication rules as other application callers. Agents can prepare drafts and submit evidence through the declared tool surface. Review and publication remain separate staff authority. The adapter never executes article steps, fetches evidence URLs, provisions a runner, or creates a second database or identity system.

createKnowledgeAgentDispatcher provides the shared operation boundary. knowledgeAgentScopes, knowledgeAgentOperations, and knowledgeAgentToolNames declare its finite surface. Inputs are validated against shared internal schemas and fixed component ceilings before dispatch. Errors use bounded public responses rather than exposing internal exceptions or private evidence and provenance.

The initial createDraft/updateDraft HTTP/MCP schemas reject sourceReferences. Atomic draft/source authoring is a privileged direct-host application extension; it adds no agent scope or tool.

createKnowledgeAgentHttp and createKnowledgeAgentMcp expose that dispatcher through host-configured protected endpoints. Both require fresh host authentication and admission control on every request; neither issues tokens.

The host composition contract describes authenticated contexts, trusted evidence, replay, and safe DTOs. The retrieval contract describes authoritative current-publication confirmation and audience boundaries.

Optional native-client report mode

createKnowledgeAgentDispatcher optionally accepts reports: Pick<KnowledgeEvidenceReports, "report" | "ledger" | "status">. This composes the shared human-report service without adding tools or scopes. The existing five operations remain getDraft, createDraft, updateDraft, getValidationRequirements and submitEvidence. Configured MCP tool schemas advertise report discovery/polling and submission variants on the latter two; HTTP uses the same envelopes. Omitting reports preserves the exact legacy schemas and results, rejecting extension fields.

The verified 0.1.3 release provides that report trio. The verified 0.1.4 release additionally accepts reports.query, typed as the optional Partial<Pick<KnowledgeEvidenceReports, "query">> extension. The dispatcher calls it once for report-aware requirements, passing only the article ID and optional owner-status key. It projects the returned governed requirements, ledger and status into the same wire result. Internal target metadata and capacity, report bodies, evidence and opaque context observations never appear as added fields. No tool, scope, schema or client option changes. Supplying only the original trio retains its existing read sequence; legacy requirements do not invoke query. A configured query's failure or malformed output refuses without falling back.

Both report variants need effective draftRead and evidenceSubmit. Requirements input adds articleId and optional reportLookup: { ledgerEpoch, reportId }, returning reportLedger and optional owner-only, body-free reportStatus. Receipt-free submitEvidence adds the current ledgerEpoch and report: { summary, details } to the original command and exact evidence fields. Its kind: "pending-human-review" result acknowledges only a report; it is not an article mutation or verified evidence.

The native client polls through that same requirements tool. A separately authorized human reviews the private report and records a decision; staff may review their own agent and no two-person rule is enforced. After confirmation, the original receipt-bearing submitEvidence form performs actual KB qualification with the exact evidence and current article generation. First confirmation preserves the report receipt; reassessment rotates its cycle. Current runner/result/build/governance and freshness checks still apply. Report bodies, reviewer details and private accepted evidence remain staff-only.

Hosts bind all report/query work to the original request, credential, principal, grant, client and resource. Keep initial request authentication. For pure reads, hosts may revalidate per port or use one request-local full-credential check before the first read and another after the completed actual dispatcher call, checking all required scopes/permissions before disclosure. MCP needs that fence inside its awaited tool callback, not only around an outer Response. Writes retain fresh before/after guards; no read group is reused across invocations. Preserve the restricted context rather than substituting current owner/Admin authority. Ledger principal resolution is not a host credential verifier.

The optional application context/read-confirm pair is trusted composition only. Its opaque observation is instance- and caller-bound, single-use read bookkeeping; it is neither authority nor an attestation and never reaches the agent or durable records. Fewer repeated reads do not prove that a complete host invocation fits the Workers Free limit of 50 D1 queries per invocation, or establish a CPU, physical-row or latency guarantee; actual host profiles remain unproven.

Read the verified 0.1.3 wire contract, native-client workflow and report lifecycle for the published report trio. The aggregate query and context/read-confirm pair shipped in verified 0.1.4; see its versioned guide. The answering read-batching 0.1.5 release is also verified. Actual client/host acceptance remains open.

Local verification and release

Repository development uses Node 22.6.0+ or 24 with pnpm 10.34.5:

pnpm install --frozen-lockfile
pnpm run format:check
pnpm run check
pnpm test
pnpm example
pnpm run release:check
pnpm run agent:proof

release:check packs and installs all four prepared Knowledge Base packages in an isolated temporary consumer, verifies their actual artifact bytes and inventory, and imports their public entry points without workspace links. agent:proof exercises the authenticated SDK path with an exact released Agent Access registry producer and the four packed KB artifacts in a fresh temporary consumer, with lifecycle scripts disabled. Agent Access remains a proof dependency rather than this package's runtime dependency. These local checks establish neither live host acceptance nor KB trusted npm publication.

Each package has its own README, MIT LICENSE, build-on-prepack hook, and compiled-test exclusion. All four package versions remain synchronized with exact internal dependency pins. Publishing, release tags, trusted-publisher configuration, and host activation are separate maintainer operations in the release procedure. The report-trio contract links above retain verified v0.1.3; aggregate query and context-pair support shipped in verified v0.1.4. The answering read-batching 0.1.5 release has its own verified receipt; changed source requires its own review and current-head gates. Source readers can use the explicitly moving DEVELOPMENT documentation on main while preparing a release. The versioned contract references remain tag-pinned; the DEVELOPMENT link is a source-reader fallback.

Built in the open by RetireGolden, LLC.