npm-agent-packaging

npm Agent Packaging

When to Use npm Distribution

npm is the right distribution channel when:

• Your agent is built with Node.js, TypeScript, or JavaScript.
• You are packaging an MCP server (the primary consumer of npx-based distribution).
• Your agent uses the Vercel AI SDK, LangChain.js, or any Node-based AI framework.
• You want users to run your agent with a single npx command, zero prior setup.
• You need cross-platform distribution (macOS, Windows, Linux) without separate binaries.
• Your target audience is developers who already have Node.js installed.

npm gives you: a global registry, dependency resolution, semantic versioning, provenance attestation, and the npx zero-install runner. No other JavaScript distribution method matches this combination.

---

package.json Anatomy for Agent Distribution

Every field matters. Here is the annotated structure for a distributable AI agent.

{
  "name": "@your-org/agent-name",
  "version": "1.0.0",
  "description": "One-line description of what this agent does",
  "type": "module",
  "bin": {
    "agent-name": "./dist/cli.js"
  },
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": [
    "dist/"
  ],
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "start": "node dist/cli.js",
    "inspect": "npx @modelcontextprotocol/inspector node dist/cli.js",
    "lint": "eslint src/",
    "test": "vitest run",
    "prepublishOnly": "npm run build && npm run test"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.12.0",
    "zod": "^3.23.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.7.0",
    "vitest": "^3.0.0"
  },
  "engines": {
    "node": ">=18.0.0"
  },
  "keywords": [
    "ai-agent",
    "mcp",
    "mcp-server",
    "cli",
    "automation"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/your-org/agent-name"
  }
}

Field-by-Field Breakdown

name -- Use a scoped name (@your-org/agent-name). Scoped packages avoid name collisions on the npm registry and signal organizational ownership. Unscoped names are fine for personal projects but become a liability at scale.