diff --git a/README.md b/README.md index e121273..6feb2b1 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ [![CI](https://github.com/Phoenixrr2113/codebase-graph/actions/workflows/ci.yml/badge.svg)](https://github.com/Phoenixrr2113/codebase-graph/actions/workflows/ci.yml) [![CodeQL](https://github.com/Phoenixrr2113/codebase-graph/actions/workflows/codeql.yml/badge.svg)](https://github.com/Phoenixrr2113/codebase-graph/actions/workflows/codeql.yml) [![GitHub stars](https://img.shields.io/github/stars/Phoenixrr2113/codebase-graph?style=flat)](https://github.com/Phoenixrr2113/codebase-graph/stargazers) +[![npm version](https://img.shields.io/npm/v/%40agntk%2Fcodegraph-mcp?style=flat)](https://www.npmjs.com/package/@agntk/codegraph-mcp) +[![npm downloads](https://img.shields.io/npm/dw/%40agntk%2Fcodegraph-mcp?style=flat)](https://www.npmjs.com/package/@agntk/codegraph-mcp) [![MIT license](https://img.shields.io/github/license/Phoenixrr2113/codebase-graph)](LICENSE) CodeGraph turns source code and project knowledge into a searchable graph for AI agents and developers. It parses code with tree-sitter, stores structural and temporal relationships in FalkorDB, and exposes five focused tools through the Model Context Protocol (MCP). @@ -10,6 +12,7 @@ CodeGraph turns source code and project knowledge into a searchable graph for AI ## Access the project - [Landing page](https://v0-landing-page-build-kappa-virid.vercel.app) +- [npm package](https://www.npmjs.com/package/@agntk/codegraph-mcp) - [Source code](https://github.com/Phoenixrr2113/codebase-graph) - [Issues](https://github.com/Phoenixrr2113/codebase-graph/issues) - [Discussions](https://github.com/Phoenixrr2113/codebase-graph/discussions) @@ -17,7 +20,7 @@ CodeGraph turns source code and project knowledge into a searchable graph for AI - [Security policy](SECURITY.md) - [MIT license](LICENSE) -The public npm package is named `@agntk/codegraph-mcp`. Its npm link, version badge, and weekly-download badge will be added after the one-time `0.1.0` bootstrap publish is verified against the registry. +The public npm package is `@agntk/codegraph-mcp`. Version `0.1.0` provides the `codegraph-mcp` and `codegraph-dashboard` bins. ## What it does @@ -31,7 +34,7 @@ The public npm package is named `@agntk/codegraph-mcp`. Its npm link, version ba ## Choose how to start -CodeGraph requires Node.js 20 or newer. The npm commands below apply after `@agntk/codegraph-mcp` is visible in the npm registry. +CodeGraph requires Node.js 20 or newer. The npm commands below install the public `@agntk/codegraph-mcp` package from the registry. ### Agent-first with MCP @@ -171,7 +174,7 @@ pnpm release:check The basic installed-tarball smoke proves the package installs in a clean consumer, both binaries start, all five MCP tools are present, a fresh database is setup-safe, Browse and indexing work, data survives restarts, the dashboard and MCP process share one embedded server, and the exact tarball hash is reported. The release CI runs that installed artifact with embedded storage on Linux x64 and Apple silicon, and checks external FalkorDB guidance on Windows x64. An opt-in local-provider lane proves cold model download progress and a usable 768-dimension vector index. -A clean-consumer local tarball proof verifies that bare `npx -y @agntk/codegraph-mcp` selects the `codegraph-mcp` bin and that `npx -y -p @agntk/codegraph-mcp codegraph-dashboard` selects the dashboard bin. Repeat both commands against the package name after publication to verify npm registry resolution. +A clean-consumer local tarball proof verifies that bare `npx -y @agntk/codegraph-mcp` selects the `codegraph-mcp` bin and that `npx -y -p @agntk/codegraph-mcp codegraph-dashboard` selects the dashboard bin. Both forms also resolve and boot from the public npm registry. ## Development diff --git a/SECURITY.md b/SECURITY.md index 08e6dae..b719138 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -19,7 +19,7 @@ The maintainer will aim to acknowledge a report within 72 hours, provide status ## Known advisories in the package dependency tree -`npm audit` reports findings against `@agntk/codegraph-mcp` that we cannot resolve from this +`npm audit` reports findings against the published `@agntk/codegraph-mcp` package that we cannot resolve from this repository. They are listed here rather than suppressed, and the release pipeline enforces the list: `pnpm audit:consumer` resolves the dependency tree an end user actually installs and fails on any unacknowledged advisory at high severity or above. An acknowledgement that diff --git a/apps/web/components/landing/hero-section.tsx b/apps/web/components/landing/hero-section.tsx index d3082fd..d55d6dc 100644 --- a/apps/web/components/landing/hero-section.tsx +++ b/apps/web/components/landing/hero-section.tsx @@ -73,10 +73,10 @@ export function HeroSection() { initial={{ opacity: 0 }} animate={{ opacity: 1 }} transition={{ delay: 0.35 }} - className="mx-auto mt-5 max-w-2xl rounded-lg border border-amber-400/30 bg-amber-400/10 px-4 py-3 text-left text-xs leading-5 text-amber-100 sm:text-sm" + className="mx-auto mt-5 max-w-2xl rounded-lg border border-emerald-400/30 bg-emerald-400/10 px-4 py-3 text-left text-xs leading-5 text-emerald-100 sm:text-sm" aria-label="Package publication status" > - Not yet published to npm. The package is @agntk/codegraph-mcp@0.1.0. The npx -y @agntk/codegraph-mcp and npx -y -p @agntk/codegraph-mcp codegraph-dashboard commands activate at publication; use the source setup today. + Available on npm. Install @agntk/codegraph-mcp@0.1.0 with npx -y @agntk/codegraph-mcp, or launch the dashboard with npx -y -p @agntk/codegraph-mcp codegraph-dashboard. diff --git a/apps/web/components/landing/release-section.tsx b/apps/web/components/landing/release-section.tsx index bf2b35c..0cf3d46 100644 --- a/apps/web/components/landing/release-section.tsx +++ b/apps/web/components/landing/release-section.tsx @@ -57,8 +57,8 @@ export function ReleaseSection() { ))} -
- Publication gate: @agntk/codegraph-mcp@0.1.0 is not in the npm registry yet. The package defines both codegraph-mcp and codegraph-dashboard bins, but registry-based install copy becomes active only after publication is verified. +
+ Published package: @agntk/codegraph-mcp@0.1.0 is available from the public npm registry with the codegraph-mcp and codegraph-dashboard bins.
diff --git a/apps/web/scripts/audit-landing.mjs b/apps/web/scripts/audit-landing.mjs index 2fdf125..dae8100 100644 --- a/apps/web/scripts/audit-landing.mjs +++ b/apps/web/scripts/audit-landing.mjs @@ -21,7 +21,6 @@ const source = (await Promise.all(sourceFiles.map((path) => readFile(path, 'utf8 const requiredClaims = [ 'Local-first code graph for AI agents and developers.', - 'Not yet published', '25 actions', 'ownership', '365 days', @@ -47,6 +46,11 @@ const requiredClaims = [ ] const forbiddenClaims = [ + /not yet published/i, + /\bunpublished\b/i, + /after publication/i, + /activates? at publication/i, + /becomes? active only after publication/i, /Jina/i, /@codegraph\/mcp/, /npx(?:\s+-y)?\s+(?!@agntk\/codegraph-mcp(?:\s|<)|-p\s+@agntk\/codegraph-mcp\s+codegraph-dashboard(?:\s|<))codegraph-(?:mcp|dashboard)/, diff --git a/docs/DISTRIBUTION-SETUP.md b/docs/DISTRIBUTION-SETUP.md index 74c11a0..61dcb6f 100644 --- a/docs/DISTRIBUTION-SETUP.md +++ b/docs/DISTRIBUTION-SETUP.md @@ -6,7 +6,7 @@ This is the operator guide for the public `@agntk/codegraph-mcp` npm package and - `main` is the source of truth. - CI validates the repository and tests one exact npm tarball on Linux, macOS, and Windows. Linux x64 and Apple silicon macOS also exercise a database-backed MCP call through embedded FalkorDBLite; the macOS job installs the module's required Homebrew `libomp` and `openssl@3` libraries first. -- The first `0.1.0` npm publication is a manual authenticated bootstrap, followed by a one-time Release workflow run that verifies the registry package and creates its annotated tag and GitHub release. +- The manual authenticated `0.1.0` npm bootstrap is complete. A one-time Release workflow run still verifies the registry package and creates its annotated tag and GitHub release. - Later annotated `vX.Y.Z` tags publish through npm trusted publishing with GitHub Actions OIDC. - The release workflow publishes or finalizes only after the installed-package matrix passes on Linux x64, Apple silicon macOS, and Windows x64. - The optional local-provider lane runs on Linux x64 with an empty model cache and proves download progress plus a usable 768-dimension vector index. @@ -21,9 +21,11 @@ This is the operator guide for the public `@agntk/codegraph-mcp` npm package and Do not create an npm automation token for this project. The steady-state workflow uses a short-lived OIDC identity. -## One-time `0.1.0` bootstrap +## Completed manual `0.1.0` bootstrap -Use a clean checkout of the reviewed commit. Confirm authentication without displaying configuration or token data: +Version `0.1.0` is public in the npm registry. The commands below preserve the completed manual bootstrap procedure for reference. The annotated tag and GitHub release remain owned by the separate bootstrap workflow. + +The procedure used a clean checkout of the reviewed commit and confirmed authentication without displaying configuration or token data: ```bash git status --short @@ -32,7 +34,7 @@ npm whoami npm view @agntk/codegraph-mcp version --json ``` -The status output must be empty. Save the full 40-character commit SHA as `BOOTSTRAP_COMMIT`; it identifies the reviewed source used to build the registry package. An npm `E404` response is expected before the first publication. Then run the full local gate: +The status output had to be empty. The full 40-character commit SHA was saved as `BOOTSTRAP_COMMIT`; it identifies the reviewed source used to build the registry package. An npm `E404` response was expected before the first publication. The full local gate was then run: ```bash pnpm install --frozen-lockfile @@ -48,15 +50,15 @@ pnpm build:mcpb pnpm release:check ``` -Publish only the exact tarball created and verified by `pnpm release:check`: +Only the exact tarball created and verified by `pnpm release:check` was published: ```bash npm publish tmp/release/agntk-codegraph-mcp-0.1.0.tgz --access public ``` -The authenticated bootstrap cannot use trusted-publishing provenance because the npm package does not exist yet. Later releases use the trusted publisher and receive automatic provenance from npm. +The authenticated bootstrap could not use trusted-publishing provenance because the npm package did not exist yet. Later releases use the trusted publisher and receive automatic provenance from npm. -If `npm whoami` fails, run `npm login` in your terminal and repeat the identity check. Never paste an npm token into GitHub, a shell command, an issue, or a chat. +For future manual recovery, if `npm whoami` fails, run `npm login` in your terminal and repeat the identity check. Never paste an npm token into GitHub, a shell command, an issue, or a chat. ## Verify the bootstrap package @@ -83,15 +85,15 @@ node scripts/release/smoke-package.mjs \ The basic smoke creates a temporary consumer and installs the exact tarball without lifecycle scripts. Its 25 runtime assertions cover the matching CLI version, dashboard health and built assets, empty projects and embedding coverage, setup status, Browse roots, MCP initialization, the exact five-tool surface (`analyze`, `codebase`, `knowledge`, `query`, and `search`), project configuration, indexing, graph queries, restart persistence, concurrent MCP and dashboard access through one embedded server, shutdown order, persisted data, and the tarball SHA-256. -Release CI runs this installed artifact with embedded FalkorDBLite on Linux x64 and Apple silicon macOS. The macOS job first runs `brew install libomp openssl@3`. The Windows x64 job verifies the exact external FalkorDB guidance without attempting embedded startup. A clean-consumer local tarball proof verifies the documented invocation shapes: bare `npx -y @agntk/codegraph-mcp` selects the MCP bin, while `npx -y -p @agntk/codegraph-mcp codegraph-dashboard` selects the dashboard bin. Repeat both commands against the package name after publication to verify npm registry resolution. +Release CI runs this installed artifact with embedded FalkorDBLite on Linux x64 and Apple silicon macOS. The macOS job first runs `brew install libomp openssl@3`. The Windows x64 job verifies the exact external FalkorDB guidance without attempting embedded startup. A clean-consumer local tarball proof verifies the documented invocation shapes: bare `npx -y @agntk/codegraph-mcp` selects the MCP bin, while `npx -y -p @agntk/codegraph-mcp codegraph-dashboard` selects the dashboard bin. Both forms also resolve and boot from the public npm registry. After the registry smoke passes, create the GitHub `npm` environment for later tag releases. In GitHub Actions, open the Release workflow, choose **Run workflow** from `main`, enter `0.1.0` as `bootstrap_version`, and enter the saved full SHA as `bootstrap_commit`. This one-time path accepts only the `0.1.0` package version, checks out that exact commit, requires it to be reachable from `main`, reruns the full release gate, confirms that the exact version already exists on npm, requires the registry tarball to be byte-for-byte identical to the artifact rebuilt from `bootstrap_commit`, creates the annotated `v0.1.0` tag on that commit, and publishes the tarball plus checksum as a GitHub release. It does not use the `npm` environment, request an OIDC token, or call `npm publish` again. -Do not push `v0.1.0` yourself after the manual npm publication. A normal tag-triggered release correctly requires its version to be unpublished; the bootstrap workflow dispatch owns the initial tag and avoids a duplicate publication attempt. +Do not push `v0.1.0` yourself after the manual npm publication. A normal tag-triggered release correctly requires its target version to be absent from the registry; the bootstrap workflow dispatch owns the initial tag and avoids a duplicate publication attempt. ## Configure trusted publishing -After `@agntk/codegraph-mcp` exists on npm, open its package settings and add a GitHub Actions trusted publisher with: +The package now exists on npm. Open its package settings and add a GitHub Actions trusted publisher with: | Field | Value | | --- | --- | diff --git a/mcp.json.example b/mcp.json.example index ed2f26a..35f0bca 100644 --- a/mcp.json.example +++ b/mcp.json.example @@ -1,19 +1,19 @@ -// Source checkout after building packages/mcp-server/dist/index.js +// Public npm package { "mcpServers": { "codegraph": { - "command": "node", - "args": ["/absolute/path/to/codebase-graph/packages/mcp-server/dist/index.js"] + "command": "npx", + "args": ["-y", "@agntk/codegraph-mcp"] } } } -// Post-publication, after @agntk/codegraph-mcp is verified in the npm registry +// Source checkout after building packages/mcp-server/dist/index.js { "mcpServers": { "codegraph": { - "command": "npx", - "args": ["-y", "@agntk/codegraph-mcp"] + "command": "node", + "args": ["/absolute/path/to/codebase-graph/packages/mcp-server/dist/index.js"] } } } diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md index dfade63..2daf238 100644 --- a/packages/mcp-server/README.md +++ b/packages/mcp-server/README.md @@ -22,6 +22,21 @@ The `codebase` `reindex` action accepts optional `historySince` and `historyMaxC Set `CODEGRAPH_RAW_TOOLS=true` using the literal string `true` to register lower-level handlers alongside the five grouped tools. Unset, `false`, and other values keep the grouped-only surface. +## Public package configuration + +Add the published package to an MCP client: + +```json +{ + "mcpServers": { + "codegraph": { + "command": "npx", + "args": ["-y", "@agntk/codegraph-mcp"] + } + } +} +``` + ## Source-checkout configuration Build the workspace before pointing an MCP client at the compiled entry: