@mackody/quickenrich-mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,54 +1,106 @@
 # Quick Enrich MCP
 
-Standalone MCP server for Quick Enrich's documented APIs. It is built for internal prospecting workflows: secure local API-key storage, exact person enrichment, reverse-email/phone lookup, domain lead pulls, contact/company finder calls, and compact batch envelopes for agent use.
+NPM package: [`@mackody/quickenrich-mcp`](https://www.npmjs.com/package/@mackody/quickenrich-mcp)
+
+Standalone MCP server and CLI for Quick Enrich's documented APIs. It is built for internal prospecting workflows: secure local API-key storage, exact person enrichment, reverse-email/phone lookup, domain lead pulls, contact/company finder calls, CSV/JSONL workflows, and compact batch envelopes for agent use.
 
 Docs source: [Quick Enrich API Documentation](https://app.quickenrich.io/docs).
 
-## Install
+## Install From NPM
 
 ```bash
-npm install
-npm run test
+npm install -g @mackody/quickenrich-mcp
+quickenrich-token set
+quickenrich-token doctor
 ```
 
-Package/agent setup after install:
+Requires Node.js 20 or newer.
+
+You can also run without a global install:
 
 ```bash
-quickenrich-token set
-quickenrich-token doctor
-quickenrich-agent-docs install --cwd /path/to/agent-project
+npx -p @mackody/quickenrich-mcp quickenrich-token set
+npx -y @mackody/quickenrich-mcp
+```
+
+## MCP Client Config
+
+Global install config:
+
+```json
+{
+  "mcpServers": {
+    "quick-enrich": {
+      "command": "quickenrich-mcp",
+      "env": {
+        "QUICKENRICH_MCP_TOOL_MODE": "agent",
+        "QUICKENRICH_MCP_RESPONSE_MODE": "compact"
+      }
+    }
+  }
+}
+```
+
+No-install `npx` config:
+
+```json
+{
+  "mcpServers": {
+    "quick-enrich": {
+      "command": "npx",
+      "args": ["-y", "@mackody/quickenrich-mcp"],
+      "env": {
+        "QUICKENRICH_MCP_TOOL_MODE": "agent",
+        "QUICKENRICH_MCP_RESPONSE_MODE": "compact"
+      }
+    }
+  }
+}
 ```
 
-`quickenrich-agent-docs install` appends exactly two managed Quick Enrich how-to-use lines to `CLAUDE.md` and `AGENTS.md` in the target project. It is idempotent. Remove those managed lines with:
+MCP server alias: `quick-enrich`
+
+Use `QUICKENRICH_MCP_TOOL_MODE=minimal` for only auth, graph, natural-language planning, and batch pull. Use `QUICKENRICH_MCP_TOOL_MODE=full` when you want every low-level endpoint and verbose schema descriptions. Default `agent` mode is the recommended NPM install mode.
+
+## Auth
 
 ```bash
-quickenrich-agent-docs uninstall --cwd /path/to/agent-project
+quickenrich-token set
+quickenrich-token status
+quickenrich-token doctor
 ```
 
-Set an API key with either an environment variable:
+The token CLI stores the key at `~/.config/quickenrich-mcp/config.json` with `0600` permissions. Env vars override the config file.
+
+For CI or ephemeral MCP hosts, set:
 
 ```bash
 export QUICKENRICH_API_KEY=...
 ```
 
-or the local secure config:
+## Agent Project Setup
+
+After installing the package, add the two managed agent hints to a project:
 
 ```bash
-node scripts/quickenrich-token.mjs set
-node scripts/quickenrich-token.mjs status
+quickenrich-agent-docs install --cwd /path/to/agent-project
 ```
 
-The token CLI stores the key at `~/.config/quickenrich-mcp/config.json` with `0600` permissions. Env vars override the config file.
-
-## MCP
+`quickenrich-agent-docs install` appends exactly two Quick Enrich how-to-use lines to `CLAUDE.md` and `AGENTS.md`. It is idempotent.
 
-Use the bundled `.mcp.json` or run directly:
+Remove those managed lines with:
 
 ```bash
-node scripts/quickenrich-mcp.mjs
+quickenrich-agent-docs uninstall --cwd /path/to/agent-project
 ```
 
-MCP server alias: `quick-enrich`
+## Package Binaries
+
+- `quickenrich-mcp`: stdio MCP server.
+- `quickenrich-token`: secure local API-key setup and auth diagnostics.
+- `quickenrich-agent-docs`: install/uninstall agent usage hints in `CLAUDE.md` and `AGENTS.md`.
+
+## Agent Tool Surface
 
 Default agent tools:
 
@@ -76,8 +128,6 @@ Full-mode tools (`QUICKENRICH_MCP_TOOL_MODE=full`) also expose:
 - `quickenrich_batch_pull_leads`
 - `quickenrich_lookup_values`
 
-Use `QUICKENRICH_MCP_TOOL_MODE=minimal` for only auth, graph, natural-language planning, and batch pull. Use `QUICKENRICH_MCP_TOOL_MODE=full` when you want every low-level endpoint and verbose schema descriptions.
-
 Default agent mode intentionally emits slim schemas and short tool descriptions so cold agents do not spend context on prose they can recover from `quickenrich_agent_graph`. The default `tools/list` surface is budgeted under 8 KB and includes lookup discovery because finder filters need valid country, industry, employee-range, revenue-range, and service values.
 
 Responses default to compact mode with a 12 KB output budget, 12 array items, 48 object keys, depth 4, and 240-character strings. Pass `response: { "mode": "full", "maxOutputChars": 64000 }` for rawer output, or `response: { "mode": "meta" }` for shape-only output.
@@ -174,7 +224,7 @@ Domain batch pulls use a shared token-bucket limiter per MCP client plus a rolli
 ```bash
 QUICKENRICH_DOMAIN_SEARCH_REQUESTS_PER_MINUTE=300 \
 QUICKENRICH_DOMAIN_SEARCH_BURST_SIZE=8 \
-node scripts/quickenrich-mcp.mjs
+quickenrich-mcp
 ```
 
 The batch result includes `throttle` metadata showing the active ceiling, burst, total acquired slots, and sleep time. Repeated calls through the same MCP process share buckets, so follow-up batches do not reset the burst. If a final 429 includes `Retry-After`, the limiter cools down before later starts.
@@ -183,7 +233,18 @@ Use `throttle_scope:"shared"` to coordinate the rolling request ceiling across m
 
 Other batch lanes also use small compliant default bursts: employee search, phone search, and reverse email default to `burst_size=16`; Contact Finder and Company Finder default to `burst_size=4`.
 
-## Smoke Tests
+## Source Development
+
+Clone the repo only if you are developing the package itself:
+
+```bash
+git clone https://github.com/codyrobertson/quickenrich-mcp.git
+cd quickenrich-mcp
+npm install
+npm run smoke
+```
+
+Run the full local plus live suite when a Quick Enrich key is configured:
 
 ```bash
 npm run test
@@ -265,19 +326,3 @@ Latest default token-bucket paid local run on 2026-07-09:
 - `direct_core_batch`: 266.64 ms, 2 requests, 2 credits, 2 leads.
 - `mcp_batch_stdio`: 318.64 ms, 2 requests, 2 credits, 2 leads.
 - Result: MCP stdio batch was 2.09x faster than naive raw sequential API usage, cut request volume 2x, and saved 50% credits on duplicate inputs.
-
-## NPM Publish Prep
-
-Dry-run the package contents before publishing:
-
-```bash
-npm run check
-npm run smoke
-npm run pack:dry-run
-```
-
-Actual publish is intentionally manual:
-
-```bash
-npm publish --access public
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mackody/quickenrich-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Standalone MCP server and CLI for Quick Enrich lead enrichment APIs.",
   "bin": {