@nestr/mcp 0.1.8 → 0.1.10

package/README.md

@@ -14,39 +14,31 @@ This MCP server allows AI assistants to interact with your Nestr workspace:
 
 ## Quick Start
 
-### 1. Get Your API Key
+**Visit [mcp.nestr.io](https://mcp.nestr.io)** for the easiest setup with step-by-step instructions for Claude Desktop, Claude Code, and Cursor.
 
-1. Go to your [Nestr workspace](https://app.nestr.io)
-2. Click **Settings** (gear icon) in the top right
-3. Go to the **Integrations** tab
-4. Find **"Workspace API access"** and click **Configure**
-5. Click **"New API key"** and copy it
-
-### 2. Configure Your AI Client
+### Claude Desktop
 
-#### Claude Desktop
+1. Go to **Settings → Connectors → Add custom connector**
+2. Set **Name** to `Nestr` and **Remote MCP URL** to `https://mcp.nestr.io/mcp`
+3. Click "Add" then "Authenticate" to log in with Nestr
 
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+### Claude Code
 
-```json
-{
-  "mcpServers": {
-    "nestr": {
-      "command": "npx",
-      "args": ["-y", "@nestr/mcp"],
-      "env": {
-        "NESTR_API_KEY": "your-api-key-here"
-      }
-    }
-  }
-}
+```bash
+claude mcp add nestr --transport http https://mcp.nestr.io/mcp
 ```
 
-Restart Claude Desktop after saving.
+Then run `/mcp` in Claude Code and click "Authenticate" to log in.
 
-#### Claude Code
+### Using the npm Package (Local)
+
+If you prefer to run the MCP server locally:
+
+```bash
+npx @nestr/mcp
+```
 
-Add to your Claude Code MCP settings:
+Configure your AI client with:
 
 ```json
 {
@@ -62,11 +54,12 @@ Add to your Claude Code MCP settings:
 }
 ```
 
-#### Cursor
-
-Add to your Cursor MCP configuration with the same format as above.
+To get an API key:
+1. Go to your [Nestr workspace](https://app.nestr.io)
+2. Click **Settings** → **Integrations** → **Workspace API access** → **Configure**
+3. Click **"New API key"** and copy it
 
-### 3. Start Using It
+## Start Using It
 
 Ask your AI assistant things like:
 
@@ -75,7 +68,6 @@ Ask your AI assistant things like:
 - "Create a new project called 'Q1 Planning'"
 - "What are my current projects and their status?"
 - "Who is responsible for customer support?"
-- "Show me the structure of the Product circle"
 
 ## Available Tools
 
@@ -100,9 +92,9 @@ Ask your AI assistant things like:
 | `nestr_list_labels` | List available labels |
 | `nestr_get_label` | Get label details |
 | `nestr_get_projects` | List projects with status |
-| `nestr_get_insights` | Get self-organization and team health metrics |
+| `nestr_get_insights` | Get workspace metrics |
 | `nestr_get_insight_history` | Get historical trend data for a metric |
-| `nestr_get_workspace_apps` | List enabled apps/features in workspace |
+| `nestr_get_workspace_apps` | List enabled apps/features |
 | `nestr_list_inbox` | List items in user's inbox (OAuth only) |
 | `nestr_create_inbox_item` | Quick capture to inbox (OAuth only) |
 | `nestr_get_inbox_item` | Get inbox item details (OAuth only) |
@@ -110,56 +102,17 @@ Ask your AI assistant things like:
 
 ## Authentication
 
-There are two ways to authenticate with the Nestr MCP server:
-
-### Option 1: API Key (Simple)
-
-API keys provide full workspace access and are the easiest way to get started. See [Quick Start](#quick-start) above.
-
-**Note:** API keys have full workspace access regardless of user permissions.
-
-### Option 2: OAuth (Recommended for Hosted Service)
-
-OAuth authentication respects user-specific permissions - the AI assistant can only access what the authenticated user can access.
-
-#### Using the Hosted Service (mcp.nestr.io)
-
-The hosted service at [mcp.nestr.io](https://mcp.nestr.io) supports OAuth out of the box:
-
-1. Visit [mcp.nestr.io/oauth/authorize](https://mcp.nestr.io/oauth/authorize)
-2. Log in with your Nestr account and authorize access
-3. Copy the access token from the success page
-4. Use the token in your MCP client configuration:
-
-```json
-{
-  "mcpServers": {
-    "nestr": {
-      "command": "npx",
-      "args": ["-y", "@nestr/mcp"],
-      "env": {
-        "NESTR_OAUTH_TOKEN": "your-oauth-token-here"
-      }
-    }
-  }
-}
-```
+### OAuth (Recommended)
 
-#### Self-Hosted OAuth Setup
+The hosted service at [mcp.nestr.io](https://mcp.nestr.io) handles OAuth automatically. Just add the server and authenticate through your browser.
 
-If you're running your own instance of the MCP server and want to enable OAuth:
+OAuth respects user-specific permissions - the AI assistant can only access what the authenticated user can access.
 
-1. **Contact Nestr** at [dev@nestr.io](mailto:dev@nestr.io) to register an OAuth client
-2. Provide your callback URL (e.g., `https://your-domain.com/oauth/callback`)
-3. Nestr will provide you with a `client_id` and `client_secret`
-4. Set the following environment variables:
+### API Key
 
-```bash
-NESTR_OAUTH_CLIENT_ID=your-client-id
-NESTR_OAUTH_CLIENT_SECRET=your-client-secret
-```
+API keys provide full workspace access and work with the local npm package. See [Quick Start](#using-the-npm-package-local) above.
 
-Once configured, users can authenticate via `/oauth/authorize` on your server.
+**Note:** API keys have full workspace access regardless of user permissions.
 
 ## Environment Variables
 
@@ -168,10 +121,8 @@ Once configured, users can authenticate via `/oauth/authorize` on your server.
 | `NESTR_API_KEY` | Nestr API key (full workspace access) | Yes* |
 | `NESTR_OAUTH_TOKEN` | OAuth token (respects user permissions) | Yes* |
 | `NESTR_API_BASE` | API base URL (default: `https://app.nestr.io/api`) | No |
-| `NESTR_OAUTH_CLIENT_ID` | OAuth client ID (for self-hosted OAuth) | No |
-| `NESTR_OAUTH_CLIENT_SECRET` | OAuth client secret (for self-hosted OAuth) | No |
 
-\* Either `NESTR_API_KEY` or `NESTR_OAUTH_TOKEN` is required.
+\* Either `NESTR_API_KEY` or `NESTR_OAUTH_TOKEN` is required for local usage.
 
 ## Development
 
@@ -199,24 +150,19 @@ npm run build
 npm run inspect
 ```
 
-## Hosted Service
-
-A hosted version is available at [mcp.nestr.io](https://mcp.nestr.io) for users who prefer not to run the server locally.
-
 ## Security
 
 - Never commit your API key or OAuth token to version control
-- API keys provide full workspace access - consider using OAuth for more granular permissions
-- OAuth tokens respect user permissions and are the recommended approach for shared environments
-- Store credentials securely (e.g., in a password manager or secrets manager)
-- Rotate keys/tokens if you suspect they've been compromised
+- OAuth tokens respect user permissions and are recommended
+- API keys provide full workspace access - use OAuth for granular permissions
+- Rotate credentials if you suspect they've been compromised
 
 ## Resources
 
+- [Setup Guide](https://mcp.nestr.io) - Step-by-step setup instructions
 - [Nestr Help Center](https://help.nestr.io)
 - [Nestr API Documentation](https://app.nestr.io/api/docs)
 - [Model Context Protocol](https://modelcontextprotocol.io)
-- [MCP Specification](https://modelcontextprotocol.io/specification/2025-11-25)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestr/mcp",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "MCP server for Nestr - connect AI assistants to your workspace",
   "author": "Nestr <dev@nestr.io>",
   "license": "MIT",

package/web/index.html

@@ -4,7 +4,7 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Nestr MCP Server - Connect AI to Your Workspace</title>
-  <meta name="description" content="Connect Claude, Cursor, Raycast, and other AI assistants to your Nestr workspace using the Model Context Protocol (MCP).">
+  <meta name="description" content="Connect Claude, Cursor, and other AI assistants to your Nestr workspace using the Model Context Protocol (MCP).">
   <link rel="stylesheet" href="styles.css">
   <link rel="icon" href="https://app.nestr.io/favicon.ico">
 </head>
@@ -31,7 +31,7 @@
       <div class="container">
         <h1>Connect AI to Your Nestr Workspace</h1>
         <p class="subtitle">
-          Use the Model Context Protocol (MCP) to let Claude, Cursor, Raycast, and other AI assistants
+          Use the Model Context Protocol (MCP) to let Claude, Cursor, and other AI assistants
           interact with your tasks, projects, circles, and roles.
         </p>
         <div class="cta-buttons">
@@ -174,40 +174,39 @@
               <button class="tab active" data-tab="claude-desktop">Claude Desktop</button>
               <button class="tab" data-tab="claude-code">Claude Code</button>
               <button class="tab" data-tab="cursor">Cursor</button>
-              <button class="tab" data-tab="raycast">Raycast</button>
             </div>
 
             <div class="tab-content active" id="claude-desktop">
-              <p>Edit your Claude Desktop configuration file:</p>
-              <ul>
-                <li><strong>macOS:</strong> <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></li>
-                <li><strong>Windows:</strong> <code>%APPDATA%\Claude\claude_desktop_config.json</code></li>
-              </ul>
-              <p>Add the following configuration:</p>
-
-              <pre class="config-block hosted oauth active"><code>{
-  "mcpServers": {
-    "nestr": {
-      "url": "https://mcp.nestr.io/mcp",
-      "headers": {
-        "Authorization": "Bearer your-oauth-token-here"
-      }
-    }
-  }
-}</code></pre>
+              <div class="config-block hosted oauth active">
+                <div class="quickstart-box">
+                  <h4>Quickstart (Recommended)</h4>
+                  <p><strong>Step 1:</strong> In Claude Desktop, go to <strong>Settings &rarr; Connectors &rarr; Add custom connector</strong></p>
+                  <p><strong>Step 2:</strong> Fill in the following:</p>
+                  <table class="field-table">
+                    <tr><td><strong>Name</strong></td><td><code>Nestr</code></td></tr>
+                    <tr><td><strong>Remote MCP URL</strong></td><td><code>https://mcp.nestr.io/mcp</code></td></tr>
+                  </table>
+                  <p><strong>Step 3:</strong> Click "Add" and then "Authenticate" to log in with your Nestr account.</p>
+                  <p class="quickstart-note">That's it! Claude Desktop will handle the OAuth flow automatically.</p>
+                </div>
+              </div>
 
-              <pre class="config-block hosted apikey"><code>{
-  "mcpServers": {
-    "nestr": {
-      "url": "https://mcp.nestr.io/mcp",
-      "headers": {
-        "X-Nestr-API-Key": "your-api-key-here"
-      }
-    }
-  }
-}</code></pre>
+              <div class="config-block hosted apikey">
+                <p>Go to <strong>Settings &rarr; Connectors &rarr; Add custom connector</strong> and fill in:</p>
+                <table class="field-table">
+                  <tr><td><strong>Name</strong></td><td><code>Nestr</code></td></tr>
+                  <tr><td><strong>Remote MCP URL</strong></td><td><code>https://mcp.nestr.io/mcp</code></td></tr>
+                  <tr><td><strong>Headers</strong></td><td><code>X-Nestr-API-Key: your-api-key-here</code></td></tr>
+                </table>
+              </div>
 
-              <pre class="config-block local oauth"><code>{
+              <div class="config-block local oauth">
+                <p>For local setup, edit your config file:</p>
+                <ul>
+                  <li><strong>macOS:</strong> <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></li>
+                  <li><strong>Windows:</strong> <code>%APPDATA%\Claude\claude_desktop_config.json</code></li>
+                </ul>
+                <pre><code>{
   "mcpServers": {
     "nestr": {
       "command": "npx",
@@ -218,8 +217,16 @@
     }
   }
 }</code></pre>
+                <p>Restart Claude Desktop after saving.</p>
+              </div>
 
-              <pre class="config-block local apikey"><code>{
+              <div class="config-block local apikey">
+                <p>For local setup, edit your config file:</p>
+                <ul>
+                  <li><strong>macOS:</strong> <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></li>
+                  <li><strong>Windows:</strong> <code>%APPDATA%\Claude\claude_desktop_config.json</code></li>
+                </ul>
+                <pre><code>{
   "mcpServers": {
     "nestr": {
       "command": "npx",
@@ -230,16 +237,18 @@
     }
   }
 }</code></pre>
-              <p>Restart Claude Desktop after saving.</p>
+                <p>Restart Claude Desktop after saving.</p>
+              </div>
             </div>
 
             <div class="tab-content" id="claude-code">
               <div class="config-block hosted oauth active">
                 <div class="quickstart-box">
                   <h4>Quickstart (Recommended)</h4>
-                  <p>Claude Code supports automatic OAuth authentication. Just run:</p>
+                  <p><strong>Step 1:</strong> Add the Nestr MCP server:</p>
                   <pre><code>claude mcp add nestr --transport http https://mcp.nestr.io/mcp</code></pre>
-                  <p class="quickstart-note">Claude Code will automatically open your browser to authenticate with Nestr. No token setup required!</p>
+                  <p><strong>Step 2:</strong> In Claude Code, run <code>/mcp</code> and click "Authenticate" next to Nestr. This will open your browser to log in with Nestr.</p>
+                  <p class="quickstart-note">That's it! Once authenticated, Claude Code can access your Nestr workspace.</p>
                 </div>
                 <p>Or, if you already have a token, add it manually:</p>
                 <pre><code>claude mcp add nestr --transport http https://mcp.nestr.io/mcp \
@@ -264,7 +273,7 @@
   --env NESTR_API_KEY=your-api-key-here</code></pre>
               </div>
 
-              <p>After adding, run <code>/mcp</code> in Claude Code to verify the connection.</p>
+              <p>Run <code>/mcp</code> anytime to check connection status or re-authenticate.</p>
             </div>
 
             <div class="tab-content" id="cursor">
@@ -323,53 +332,6 @@
               <p>Restart Cursor after saving.</p>
             </div>
 
-            <div class="tab-content" id="raycast">
-              <p>In Raycast, go to <strong>Settings &rarr; Extensions &rarr; AI &rarr; MCP Servers</strong>, then press <kbd>&#8984;N</kbd> to add a new server.</p>
-
-              <div class="config-block hosted oauth active">
-                <p>Fill in the following fields:</p>
-                <table class="field-table">
-                  <tr><td><strong>Name</strong></td><td><code>Nestr</code></td></tr>
-                  <tr><td><strong>Transport</strong></td><td>HTTP</td></tr>
-                  <tr><td><strong>URL</strong></td><td><code>https://mcp.nestr.io/mcp</code></td></tr>
-                  <tr><td><strong>HTTP Headers</strong></td><td>Click "Add Item" and add:<br><code>Authorization</code> = <code>Bearer your-oauth-token</code></td></tr>
-                </table>
-              </div>
-
-              <div class="config-block hosted apikey">
-                <p>Fill in the following fields:</p>
-                <table class="field-table">
-                  <tr><td><strong>Name</strong></td><td><code>Nestr</code></td></tr>
-                  <tr><td><strong>Transport</strong></td><td>HTTP</td></tr>
-                  <tr><td><strong>URL</strong></td><td><code>https://mcp.nestr.io/mcp</code></td></tr>
-                  <tr><td><strong>HTTP Headers</strong></td><td>Click "Add Item" and add:<br><code>X-Nestr-API-Key</code> = <code>your-api-key</code></td></tr>
-                </table>
-              </div>
-
-              <div class="config-block local oauth">
-                <p>Fill in the following fields:</p>
-                <table class="field-table">
-                  <tr><td><strong>Name</strong></td><td><code>Nestr</code></td></tr>
-                  <tr><td><strong>Transport</strong></td><td>Standard Input/Output</td></tr>
-                  <tr><td><strong>Command</strong></td><td><code>npx</code></td></tr>
-                  <tr><td><strong>Arguments</strong></td><td><code>-y @nestr/mcp</code></td></tr>
-                  <tr><td><strong>Environment</strong></td><td>Click "Add Item" and add:<br><code>NESTR_OAUTH_TOKEN</code> = <code>your-oauth-token</code></td></tr>
-                </table>
-              </div>
-
-              <div class="config-block local apikey">
-                <p>Fill in the following fields:</p>
-                <table class="field-table">
-                  <tr><td><strong>Name</strong></td><td><code>Nestr</code></td></tr>
-                  <tr><td><strong>Transport</strong></td><td>Standard Input/Output</td></tr>
-                  <tr><td><strong>Command</strong></td><td><code>npx</code></td></tr>
-                  <tr><td><strong>Arguments</strong></td><td><code>-y @nestr/mcp</code></td></tr>
-                  <tr><td><strong>Environment</strong></td><td>Click "Add Item" and add:<br><code>NESTR_API_KEY</code> = <code>your-api-key</code></td></tr>
-                </table>
-              </div>
-
-              <p>Save the server and it will be available in Raycast AI.</p>
-            </div>
           </div>
         </div>