# Publishing to npm

This package is intended to be published under the npm organization scope:

```text
@apidance/mcp
```

The executable command remains:

```text
apidance-mcp
```

## 1. Create the npm Organization

Create or sign in to an npm user account, then create the `apidance` organization from the npm website:

1. Go to https://www.npmjs.com and sign in.
2. Open the profile menu in the upper-right corner.
3. Choose **Add an Organization**.
4. Set the organization name to `apidance`.
5. Choose the free public-package plan if this package should be public.
6. Invite collaborators if needed.

The organization name is also the npm package scope, so `apidance` becomes `@apidance`.

## 2. Verify the Local Package

```bash
cd /Users/guang/ws/web3/apidance/apidance-mcp
npm run check
npm pack --dry-run
```

If your local npm cache has permission issues, use a temporary cache:

```bash
env npm_config_cache=/private/tmp/apidance-npm-cache npm pack --dry-run
```

Review the tarball contents and make sure no secrets are included.

Also confirm the root README is present in the dry-run output. npm renders the package page from README metadata captured at publish time; if the registry page says "This package does not have a README", publish a new patch version from the package root after verifying `README.md` is included.

## 3. Log in to npm

```bash
npm login
npm whoami
```

If your account uses two-factor authentication, keep your one-time password ready.

## 4. Publish the Package

Scoped packages default to private visibility unless public access is specified. This package sets:

```json
{
  "publishConfig": {
    "access": "public"
  }
}
```

Publish:

```bash
npm publish --access public
```

After publishing, the package should be available at:

```text
https://www.npmjs.com/package/@apidance/mcp
```

## 5. Smoke Test the Published Package

```bash
npx -y @apidance/mcp --version
npx -y @apidance/mcp --list-tools
```

Then update MCP clients to use:

```json
{
  "command": "npx",
  "args": ["-y", "@apidance/mcp"]
}
```

## 6. Publishing Later Versions

Update the version before every new publish:

```bash
npm version patch
npm publish --access public
```

Use `minor` or `major` instead of `patch` when the change requires it.

## npm README Relative Links

npm renders only the package-root `README.md`. Keep only `README.md` at the package root so npm does not choose another top-level README variant as the package README.

For scoped packages, a relative link such as `./README.zh-CN.md` from the npm package page may resolve to a broken URL like:

```text
https://www.npmjs.com/package/@apidance/README.zh-CN.md
```

Use an absolute URL instead. Prefer jsDelivr for the Chinese README because it sends `charset=utf-8`; unpkg may send `text/markdown` without a charset, which can make Chinese text appear garbled in some browsers.

```text
https://cdn.jsdelivr.net/npm/@apidance/mcp@latest/docs/README.zh-CN.md
```

## Notes

- Do not publish `.env` files or real API keys.
- Keep `APIDANCE_API_KEY` and `APIDANCE_AUTH_TOKEN` as runtime environment variables.
- If `@apidance/mcp` is already taken, choose another package name under the same organization, such as `@apidance/twitter-mcp`.