@entergram/mcp 0.1.0 → 0.1.2

package/README.md

@@ -2,26 +2,19 @@
 
 Official npm CLI for connecting local MCP hosts to the public Entergram MCP gateway.
 
-This package is for local MCP hosts that can only launch local commands, such as Codex, Claude Desktop, and similar tools. It handles:
+Use this package when your MCP host can launch a local command but cannot connect directly to Entergram over OAuth on its own. `entergram-mcp` handles:
 
-- OAuth login against the Entergram MCP gateway
-- secure local token storage
-- a local `stdio` bridge that proxies requests to the public Entergram MCP gateway
-- ready-to-paste host config snippets
-
-Architecture:
-
-`Local MCP host -> entergram-mcp (stdio bridge) -> Entergram MCP gateway -> Entergram Public API`
+- OAuth login
+- local token storage
+- a local `stdio` bridge for MCP hosts such as Codex and Claude Desktop
 
 ## Install
 
-Global install:
-
 ```bash
 npm install -g @entergram/mcp
 ```
 
-Or run it on demand:
+Or run it without a global install:
 
 ```bash
 npx -y @entergram/mcp serve
@@ -43,7 +36,7 @@ entergram-mcp login --env dev
 entergram-mcp serve --env dev
 ```
 
-If you use a non-default OAuth client, pass it explicitly during login and in your MCP host config:
+If you use a custom OAuth client, pass it explicitly:
 
 ```bash
 entergram-mcp login --env dev --client-id entergram-ws-your-client-id
@@ -51,86 +44,42 @@ entergram-mcp login --env dev --client-id entergram-ws-your-client-id
 
 ## Commands
 
-Show help:
-
 ```bash
 entergram-mcp --help
-```
-
-Login:
-
-```bash
 entergram-mcp login
-entergram-mcp login --env dev
-entergram-mcp login --env dev --client-id entergram-ws-your-client-id
-```
-
-Start the local bridge:
-
-```bash
-entergram-mcp serve
-entergram-mcp serve --env dev
-```
-
-Show the currently authenticated actor:
-
-```bash
 entergram-mcp whoami
-```
-
-Clear the local session for the selected environment and client:
-
-```bash
 entergram-mcp logout
-entergram-mcp logout --env dev --client-id entergram-ws-your-client-id
+entergram-mcp serve
+entergram-mcp print-config
 ```
 
-Print a host config snippet:
+Useful flags:
 
-```bash
-entergram-mcp print-config
-entergram-mcp print-config --format toml
-entergram-mcp print-config --env dev --client-id entergram-ws-your-client-id --format toml
-```
+- `--env dev|production`
+- `--client-id ...`
+- `--scope "..."`
+- `--format json|toml`
 
 ## Host Config
 
-### JSON hosts
+For JSON-based MCP hosts:
 
 ```bash
 entergram-mcp print-config --name entergram
 ```
 
-Example output:
-
-```json
-{
-  "mcpServers": {
-    "entergram": {
-      "command": "npx",
-      "args": ["-y", "@entergram/mcp", "serve"],
-      "env": {
-        "ENTERGRAM_MCP_ENV": "production",
-        "ENTERGRAM_MCP_CLIENT_ID": "entergram-mcp-cli",
-        "ENTERGRAM_MCP_SCOPE": "workspace.read members.read accounts.read contacts.read chats.read messages.read messages.write custom_fields.read custom_fields.write tickets.read offline_access"
-      }
-    }
-  }
-}
-```
-
-### TOML hosts such as Codex
+For TOML-based hosts such as Codex:
 
 ```bash
-entergram-mcp print-config --format toml --name entergram-dev --env dev --client-id entergram-ws-your-client-id
+entergram-mcp print-config --format toml --name entergram-dev
 ```
 
-Example output:
+Example TOML config:
 
 ```toml
 [mcp_servers.entergram-dev]
-command = "npx"
-args = ["-y", "@entergram/mcp", "serve"]
+command = "entergram-mcp"
+args = ["serve"]
 
 [mcp_servers.entergram-dev.env]
 ENTERGRAM_MCP_ENV = "dev"
@@ -138,30 +87,7 @@ ENTERGRAM_MCP_CLIENT_ID = "entergram-ws-your-client-id"
 ENTERGRAM_MCP_SCOPE = "workspace.read members.read accounts.read contacts.read chats.read messages.read messages.write custom_fields.read custom_fields.write tickets.read offline_access"
 ```
 
-If your host already uses the globally installed binary, you can replace the command section with:
-
-```toml
-[mcp_servers.entergram-dev]
-command = "entergram-mcp"
-args = ["serve"]
-```
-
-## Environment Overrides
-
-You can override the built-in defaults with environment variables:
-
-- `ENTERGRAM_MCP_ENV`
-- `ENTERGRAM_MCP_GATEWAY_URL`
-- `ENTERGRAM_MCP_CLIENT_ID`
-- `ENTERGRAM_MCP_SCOPE`
-- `ENTERGRAM_MCP_CALLBACK_PORT`
-- `ENTERGRAM_MCP_CONFIG_DIR`
-
-Default local OAuth callback:
-
-`http://127.0.0.1:8787/oauth/callback`
-
-## Built-in Environments
+## Defaults
 
 Production:
 
@@ -173,94 +99,53 @@ Development:
 - gateway: `https://devmcp.entergram.com/mcp`
 - client id: `entergram-dev-mcp-client`
 
-## Local Session Storage
-
-By default, Entergram MCP stores local session files in:
+Default local OAuth callback:
 
-`~/.entergram-mcp/`
+`http://127.0.0.1:8787/oauth/callback`
 
-Each environment and client id gets its own session file, so you can keep separate sessions for:
+Session files are stored in:
 
-- production vs dev
-- personal vs workspace OAuth clients
-- multiple workspace clients with different scopes
+`~/.entergram-mcp/`
 
-## Choosing the Right OAuth Client
+## Choosing a Client
 
-Use a personal client when you want a seat-scoped local agent with safer read-only access.
+Use a personal client for seat-scoped access.
 
-Use a workspace client when you need broader scopes such as:
+Use a workspace client if you need broader scopes such as:
 
 - `members.read`
 - `messages.write`
 - `custom_fields.read`
 - `custom_fields.write`
 
-If your consent screen does not show the scopes you expect, the OAuth client itself is missing those `allowedScopes`. Update the client in Entergram first, then run login again.
+If the consent screen does not show the scopes you expect, update that OAuth client's `allowedScopes` in Entergram first, then run login again.
 
 ## Troubleshooting
 
-### `invalid_scope`
-
-The selected OAuth client does not allow one or more requested scopes.
-
-Fix:
-
-1. update the OAuth client in Entergram so its `allowedScopes` include the requested scopes
-2. run `entergram-mcp login` again
-
-### `MCP startup failed: handshaking with MCP server failed`
+`invalid_scope`
 
-Your MCP host started the local bridge, but the bridge could not authenticate or connect cleanly to the remote Entergram MCP gateway.
+- Your OAuth client does not allow one or more requested scopes.
+- Update the client in Entergram, then run `entergram-mcp login` again.
 
-Fix:
+`MCP startup failed: handshaking with MCP server failed`
 
-1. run login first for the same environment and client id used by the host
-2. make sure the host config includes the correct `ENTERGRAM_MCP_CLIENT_ID`
-3. restart the MCP host after login
+- Your MCP host started the local bridge, but the bridge could not authenticate with the remote gateway.
+- Make sure you ran login first for the same `--env` and `--client-id` used by the host.
 
-### `401` or expired token errors
+`401` or expired token errors
 
-The local session is stale or no longer refreshable.
-
-Fix:
+- Clear the local session and log in again:
 
 ```bash
 entergram-mcp logout --env dev --client-id entergram-ws-your-client-id
 entergram-mcp login --env dev --client-id entergram-ws-your-client-id
 ```
 
-### Browser opens during MCP host startup
-
-For local MCP hosts, the intended flow is:
-
-1. run `entergram-mcp login` yourself first
-2. then let the host run `entergram-mcp serve`
-
-The bridge is designed to reuse an existing local session instead of performing interactive login during the MCP handshake.
-
 ## Development
 
-Build:
-
 ```bash
 npm run build
-```
-
-Typecheck:
-
-```bash
 npm run typecheck
-```
-
-CLI smoke test:
-
-```bash
 npm run smoke:cli
-```
-
-Dry-run the publish tarball:
-
-```bash
 npm run pack:dry-run
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entergram/mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "Official Entergram MCP CLI for local MCP hosts with OAuth login, stdio bridging, and host config helpers.",
   "type": "module",