From 54caf79e2e8bb6496ea54e1fb06ce0968af78b1d Mon Sep 17 00:00:00 2001 From: simaonogueira101 Date: Tue, 12 May 2026 00:23:28 +0100 Subject: [PATCH 1/2] docs(readme): add hosted MCP install + fix stale tool table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two things were missing or wrong in the README after the 0.3.0 surface change: 1. The hosted MCP endpoint at https://mcp.noticed.so/api/mcp wasn't documented anywhere. For HTTP-capable clients (Claude Code, Cursor, Claude Desktop, etc.) it's a single-command install with no npx and no env vars. Now documented as the recommended option above the stdio walkthrough. 2. The 'MCP tools' table near the bottom still listed search_network and get_connection_path — the legacy tools from 0.2.x. They're now capability names accessed via execute, not MCP tools. Replaced with the search + execute meta-tools, an example client-side flow, and a short list of what the ~50 chat-safe capabilities cover. Also nested the per-client snippets (Claude Desktop, Cursor, …) under a new 'Stdio MCP server' h3 so the two install paths are clearly distinguished. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 60 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 2e45b0d..a256f7e 100644 --- a/README.md +++ b/README.md @@ -21,9 +21,36 @@ The MCP server exposes two meta-tools — **`search`** and **`execute`** — bac > Upgrading from 0.2.x? The tool surface changed: clients that called `search_network` / `get_connection_path` directly should now call `search` (to discover the capability) followed by `execute { capability: "search_network", args: { query: "…" } }`. MCP-aware LLMs handle this discovery automatically. -Pick your client below. +You have two ways to connect: **hosted** (no install, Streamable HTTP) or **stdio** (this package via `npx`). The hosted server runs your queries against `noticed.so` so anyone with a noticed account can use it. The stdio server is useful when your MCP client can't speak HTTP, or when you're running a self-hosted noticed instance. -### Claude Code +### Hosted MCP server (recommended — no install) + +Point any MCP client that supports Streamable HTTP at `https://mcp.noticed.so/api/mcp` with your noticed API key as a Bearer header. Mint a key at [noticed.so/dashboard/api-keys](https://noticed.so/dashboard/api-keys). + +**Claude Code** (one command): + +```bash +claude mcp add --transport http --scope user noticed https://mcp.noticed.so/api/mcp --header "Authorization: Bearer nk_live_…" +``` + +**Cursor, Claude Desktop, Zed, VS Code Copilot, Windsurf, Cline** — all support URL + header config. Drop the `command/args/env` block from any of the stdio snippets below and replace with: + +```json +{ + "mcpServers": { + "noticed": { + "url": "https://mcp.noticed.so/api/mcp", + "headers": { "Authorization": "Bearer nk_live_…" } + } + } +} +``` + +### Stdio MCP server (this package) + +Pick your client below for the stdio install. + +#### Claude Code ```bash claude mcp add --scope project noticed -- npx -y @noticed/cli mcp @@ -31,7 +58,7 @@ claude mcp add --scope project noticed -- npx -y @noticed/cli mcp `--scope project` writes to `.mcp.json` at your repo root so the server is shared with everyone on the team. Drop the flag for a personal-scope install. -### Claude Desktop +#### Claude Desktop Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows): @@ -50,7 +77,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o } ``` -### Cursor +#### Cursor Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): @@ -66,7 +93,7 @@ Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): } ``` -### VS Code (Copilot Chat, GitHub Copilot agent mode) +#### VS Code (Copilot Chat, GitHub Copilot agent mode) Edit `.vscode/mcp.json` for workspace, or run **MCP: Open User Configuration** for global: @@ -85,7 +112,7 @@ Edit `.vscode/mcp.json` for workspace, or run **MCP: Open User Configuration** f Note VS Code uses `servers` (not `mcpServers`) and requires `type`. -### Windsurf +#### Windsurf Edit `~/.codeium/windsurf/mcp_config.json`: @@ -101,7 +128,7 @@ Edit `~/.codeium/windsurf/mcp_config.json`: } ``` -### Cline (VS Code) +#### Cline (VS Code) Edit `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`: @@ -117,7 +144,7 @@ Edit `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-d } ``` -### Continue +#### Continue MCP works in **agent mode** only. Add `.continue/mcpServers/noticed.yaml`: @@ -131,7 +158,7 @@ mcpServers: NOTICED_API_KEY: nk_live_… ``` -### Zed +#### Zed Edit `~/.config/zed/settings.json` (note: key is `context_servers`, not `mcpServers`): @@ -281,18 +308,39 @@ Precedence: CLI flags > environment variables > config file. ## MCP tools +The MCP server exposes exactly two tools — both meta-tools that bridge to the noticed agent's capability registry. The client's LLM uses `search` to discover capabilities at runtime, then calls `execute` by name. + | Tool | Description | |------|-------------| -| `search_network` | Search developers by name, company, skill, or topic. Optional `source`, `sort`, `limit`, `offset`, `include_paths`. | -| `get_connection_path` | Find the shortest path to a target person. Accepts a natural-language `query`, an explicit `github_user_id`, or a `linkedin_username`. | +| `search` | Discover noticed capabilities by keyword and optional category. Returns names, descriptions, categories, and JSON parameter schemas. Call with no arguments to list everything. | +| `execute` | Run a capability by exact name. Pass capability arguments in the `args` object. | + +Example client-side flow: + +```jsonc +// 1. Find the right capability +tools/call search { "query": "missions" } +// → returns [{ name: "list_missions", parameters: {…}, … }, …] + +// 2. Run it +tools/call execute { "capability": "list_missions", "args": {} } +// → returns the user's missions +``` + +The ~50 chat-safe capabilities cover developer-network search (`search_network`, `get_connection_path`, `my_profile`, `my_network`, `my_activity`, …), missions/goals/milestones, PRM (people / interactions / stages), virtual filesystem and persona files, persistent memory, web search and fetch, and cron scheduling. Nine chat-only capabilities (in-chat messaging, referral invites, Cursor Cloud agents) are filtered server-side. Test with the MCP Inspector: ```bash +# stdio npx @modelcontextprotocol/inspector npx @noticed/cli mcp + +# hosted (Streamable HTTP) — set Authorization: Bearer in the inspector UI +npx @modelcontextprotocol/inspector +# URL: https://mcp.noticed.so/api/mcp ``` -Or by hand: +Or by hand against the stdio server: ```bash echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | noticed mcp From 7afd7fa48ebf4c9359c1802bd37836d23c25792b Mon Sep 17 00:00:00 2001 From: simaonogueira101 Date: Tue, 12 May 2026 00:27:42 +0100 Subject: [PATCH 2/2] feat(cli): default to hosted noticed.so; demote self-host to footnote MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Self-hosting noticed isn't realistic for ~100% of users — the value depends on a pre-ingested GHArchive + LinkedIn graph (hundreds of GiB of ClickHouse, paid RapidAPI access, OpenAI/Anthropic keys, NextAuth OAuth apps). The README pretending it's the common case was misleading and added friction for everyone. Changes: - src/api-client.ts: createClientFromEnv() now defaults NOTICED_API_URL to https://www.noticed.so when unset. NOTICED_API_KEY is still required. Self-hosters can override NOTICED_API_URL explicitly. - mcp.json + server.json: drop NOTICED_API_URL from required env; server.json marks it isRequired: false with a clarifying description. - README.md: purge `https://your-instance.noticed.so` from every client snippet (~10 occurrences); update the env-var table; new 'Self-hosting noticed' footnote that keeps the override documented without leading with it. - package.json + server.json: bump 0.3.0 → 0.3.1 (patch — the env-var fallback is a small behavioural addition, not a breaking change). Auto-release workflow (merged in PR #2) will pick up the version change on merge and publish 0.3.1 to npm automatically. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 37 +++++++++++++++++++++++++------------ mcp.json | 1 - package.json | 2 +- server.json | 8 ++++---- src/api-client.ts | 24 ++++++++++++++++-------- 5 files changed, 46 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index a256f7e..00d0ae9 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,6 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o "command": "npx", "args": ["-y", "@noticed/cli", "mcp"], "env": { - "NOTICED_API_URL": "https://your-instance.noticed.so", "NOTICED_API_KEY": "nk_live_…" } } @@ -87,7 +86,7 @@ Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): "noticed": { "command": "npx", "args": ["-y", "@noticed/cli", "mcp"], - "env": { "NOTICED_API_URL": "https://your-instance.noticed.so", "NOTICED_API_KEY": "nk_live_…" } + "env": { "NOTICED_API_KEY": "nk_live_…" } } } } @@ -104,7 +103,7 @@ Edit `.vscode/mcp.json` for workspace, or run **MCP: Open User Configuration** f "type": "stdio", "command": "npx", "args": ["-y", "@noticed/cli", "mcp"], - "env": { "NOTICED_API_URL": "https://your-instance.noticed.so", "NOTICED_API_KEY": "nk_live_…" } + "env": { "NOTICED_API_KEY": "nk_live_…" } } } } @@ -122,7 +121,7 @@ Edit `~/.codeium/windsurf/mcp_config.json`: "noticed": { "command": "npx", "args": ["-y", "@noticed/cli", "mcp"], - "env": { "NOTICED_API_URL": "https://your-instance.noticed.so", "NOTICED_API_KEY": "nk_live_…" } + "env": { "NOTICED_API_KEY": "nk_live_…" } } } } @@ -138,7 +137,7 @@ Edit `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-d "noticed": { "command": "npx", "args": ["-y", "@noticed/cli", "mcp"], - "env": { "NOTICED_API_URL": "https://your-instance.noticed.so", "NOTICED_API_KEY": "nk_live_…" } + "env": { "NOTICED_API_KEY": "nk_live_…" } } } } @@ -154,7 +153,6 @@ mcpServers: command: npx args: ["-y", "@noticed/cli", "mcp"] env: - NOTICED_API_URL: https://your-instance.noticed.so NOTICED_API_KEY: nk_live_… ``` @@ -168,7 +166,7 @@ Edit `~/.config/zed/settings.json` (note: key is `context_servers`, not `mcpServ "noticed": { "command": "npx", "args": ["-y", "@noticed/cli", "mcp"], - "env": { "NOTICED_API_URL": "https://your-instance.noticed.so", "NOTICED_API_KEY": "nk_live_…" } + "env": { "NOTICED_API_KEY": "nk_live_…" } } } } @@ -202,9 +200,8 @@ git clone https://github.com/noticedso/cli ~/.claude/plugins/noticed ## Quick start (CLI) ```bash -# 1. Mint an API key in your noticed dashboard at /dashboard/api-keys +# 1. Mint an API key at https://www.noticed.so/dashboard/api-keys # 2. Configure credentials -noticed config --set-url https://your-instance.noticed.so noticed config --set-key nk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 3. Search your network @@ -298,8 +295,8 @@ noticed completion fish > ~/.config/fish/completions/noticed.fish | Variable | Description | Required | |----------|-------------|----------| -| `NOTICED_API_URL` | Base URL of your noticed instance | yes | -| `NOTICED_API_KEY` | API key for authentication | yes | +| `NOTICED_API_KEY` | API key minted at https://www.noticed.so/dashboard/api-keys | yes | +| `NOTICED_API_URL` | Override the noticed instance URL. Defaults to `https://www.noticed.so` — only set this if you self-host | no | | `NOTICED_BASE_URL` | Alias for `NOTICED_API_URL` | no | Precedence: CLI flags > environment variables > config file. @@ -355,7 +352,7 @@ echo '{"jsonrpc":"2.0","method":"tools/list","id":2}' | noticed mcp import { NoticedApiClient } from "@noticed/cli"; const client = new NoticedApiClient({ - baseUrl: "https://your-instance.noticed.so", + baseUrl: "https://www.noticed.so", apiKey: "nk_live_…", }); @@ -379,6 +376,22 @@ npm run check-types --- +## Self-hosting noticed + +The CLI defaults to the hosted noticed instance at `https://www.noticed.so`. Self-hosting noticed itself is possible but operationally heavy — the value depends on a pre-ingested GitHub + LinkedIn collaboration graph (hundreds of GiB of ClickHouse data, daily GHArchive ingestion, paid LinkedIn API access, OpenAI + Anthropic keys, NextAuth OAuth apps). Most users want the hosted service. + +If you do run your own instance, set `NOTICED_API_URL` to its URL — everything else works the same: + +```bash +export NOTICED_API_URL=https://noticed.your-domain.com +export NOTICED_API_KEY=nk_live_… +noticed search "AI engineers" +``` + +The source for the hosted service lives at https://github.com/noticedso/noticed. + +--- + ## License [MIT](LICENSE) © noticed diff --git a/mcp.json b/mcp.json index cf97d64..5d6cc2d 100644 --- a/mcp.json +++ b/mcp.json @@ -4,7 +4,6 @@ "command": "npx", "args": ["-y", "@noticed/cli", "mcp"], "env": { - "NOTICED_API_URL": "https://your-instance.noticed.so", "NOTICED_API_KEY": "your-api-key" } } diff --git a/package.json b/package.json index fd4dc62..333d626 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@noticed/cli", - "version": "0.3.0", + "version": "0.3.1", "description": "CLI and MCP server for noticed — search your developer network, trace connections, find the shortest path to anyone through GitHub and LinkedIn.", "keywords": [ "noticed", diff --git a/server.json b/server.json index 986549c..414ec98 100644 --- a/server.json +++ b/server.json @@ -2,7 +2,7 @@ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.noticedso/cli", "description": "Search your developer network and trace connection paths via GitHub & LinkedIn.", - "version": "0.3.0", + "version": "0.3.1", "repository": { "url": "https://github.com/noticedso/cli", "source": "github" @@ -11,7 +11,7 @@ { "registryType": "npm", "identifier": "@noticed/cli", - "version": "0.3.0", + "version": "0.3.1", "transport": { "type": "stdio" }, "runtimeHint": "npx", "runtimeArguments": [ @@ -23,8 +23,8 @@ "environmentVariables": [ { "name": "NOTICED_API_URL", - "description": "Base URL of your noticed instance (e.g. https://noticed.so)", - "isRequired": true + "description": "Base URL of the noticed instance. Defaults to https://www.noticed.so — only set this if you self-host noticed.", + "isRequired": false }, { "name": "NOTICED_API_KEY", diff --git a/src/api-client.ts b/src/api-client.ts index 4297a0d..230675a 100644 --- a/src/api-client.ts +++ b/src/api-client.ts @@ -247,20 +247,28 @@ export class NoticedApiClient { // Config helpers // --------------------------------------------------------------------------- +/** + * The canonical hosted noticed instance. Self-hosting noticed is technically + * possible but operationally unrealistic — the value depends on a pre-ingested + * GHArchive + LinkedIn graph that takes weeks to build. Defaulting to the + * hosted service is the right tradeoff for ~100% of users. + * + * Self-hosters can still override by setting NOTICED_API_URL or + * NOTICED_BASE_URL explicitly. + */ +const DEFAULT_BASE_URL = "https://www.noticed.so"; + export function createClientFromEnv(): NoticedApiClient { - const baseUrl = process.env["NOTICED_API_URL"] ?? process.env["NOTICED_BASE_URL"]; + const baseUrl = + process.env["NOTICED_API_URL"] ?? + process.env["NOTICED_BASE_URL"] ?? + DEFAULT_BASE_URL; const apiKey = process.env["NOTICED_API_KEY"]; - if (!baseUrl) { - throw new Error( - "Missing NOTICED_API_URL or NOTICED_BASE_URL environment variable.\n" + - "Set it to the URL of your noticed instance (e.g. https://noticed.so).", - ); - } if (!apiKey) { throw new Error( "Missing NOTICED_API_KEY environment variable.\n" + - "Create an API key in your noticed dashboard.", + "Mint an API key at https://www.noticed.so/dashboard/api-keys.", ); }