{
  "markdown": "# @noticed/cli\n\n[![npm version](https://img.shields.io/npm/v/@noticed/cli.svg)](https://www.npmjs.com/package/@noticed/cli)\n[![npm downloads](https://img.shields.io/npm/dm/@noticed/cli.svg)](https://www.npmjs.com/package/@noticed/cli)\n[![CI](https://github.com/noticedso/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/noticedso/cli/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nCLI, MCP server, and Claude Code plugin for [noticed](https://noticed.so) — search your developer network, trace connections, and find the shortest path to anyone through GitHub and LinkedIn collaboration graphs.\n\n```bash\nnpm install -g @noticed/cli\nnoticed search \"AI engineers\"\nnoticed path @sarahml\n```\n\n---\n\n## Add to your AI coding agent\n\nThe MCP server exposes two meta-tools — **`search`** and **`execute`** — backed by ~50 noticed capabilities: developer-network search and connection paths, mission and goal tracking, a PRM (people-relationship-management) board, a virtual filesystem for agent workspace files, persistent memory, web search, scheduled crons, and more. Same surface the noticed web and Telegram agents use. Chat-only capabilities (in-chat messaging, referral invites, the Cursor Cloud bridge) are filtered server-side.\n\n> 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.\n\nYou 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.\n\n### Hosted MCP server (recommended — no install)\n\n`https://mcp.noticed.so/api/mcp` is a hosted Streamable HTTP endpoint. Two authentication paths are supported; pick whichever your client prefers.\n\n#### OAuth (claude.ai web, ChatGPT MCP, anything that does OAuth discovery)\n\nThe hosted server is a spec-compliant OAuth 2.1 authorization server with Dynamic Client Registration. Clients that follow the [MCP authorization profile](https://modelcontextprotocol.io/specification/draft/basic/authorization) — including claude.ai's custom connectors and ChatGPT's MCP integration — discover the server, register themselves, and walk the user through a consent screen automatically. No API key needed in the client config.\n\n**claude.ai custom connector**: open Settings → Connectors → Add custom connector, paste `https://mcp.noticed.so/api/mcp` as the URL. claude.ai handles the rest. Connected applications are visible (and revocable) at [noticed.so/dashboard/oauth-grants](https://noticed.so/dashboard/oauth-grants).\n\n#### API key Bearer (Claude Code, Cursor, anything that supports a custom header)\n\nFor clients that can set an `Authorization: Bearer …` header, mint a key at [noticed.so/dashboard/api-keys](https://noticed.so/dashboard/api-keys) and use it directly — no OAuth flow needed.\n\n**Claude Code** (one command):\n\n```bash\nclaude mcp add --transport http --scope user noticed https://mcp.noticed.so/api/mcp --header \"Authorization: Bearer nk_live_…\"\n```\n\n**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:\n\n```json\n{\n  \"mcpServers\": {\n    \"noticed\": {\n      \"url\": \"https://mcp.noticed.so/api/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer nk_live_…\" }\n    }\n  }\n}\n```\n\n### Stdio MCP server (this package)\n\nPick your client below for the stdio install.\n\n#### Claude Code\n\n```bash\nclaude mcp add --scope project noticed -- npx -y @noticed/cli mcp\n```\n\n`--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.\n\n#### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"noticed\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@noticed/cli\", \"mcp\"],\n      \"env\": {\n        \"NOTICED_API_KEY\": \"nk_live_…\"\n      }\n    }\n  }\n}\n```\n\n#### Cursor\n\nEdit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):\n\n```json\n{\n  \"mcpServers\": {\n    \"noticed\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@noticed/cli\", \"mcp\"],\n      \"env\": { \"NOTICED_API_KEY\": \"nk_live_…\" }\n    }\n  }\n}\n```\n\n#### VS Code (Copilot Chat, GitHub Copilot agent mode)\n\nEdit `.vscode/mcp.json` for workspace, or run **MCP: Open User Configuration** for global:\n\n```json\n{\n  \"servers\": {\n    \"noticed\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@noticed/cli\", \"mcp\"],\n      \"env\": { \"NOTICED_API_KEY\": \"nk_live_…\" }\n    }\n  }\n}\n```\n\nNote VS Code uses `servers` (not `mcpServers`) and requires `type`.\n\n#### Windsurf\n\nEdit `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"noticed\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@noticed/cli\", \"mcp\"],\n      \"env\": { \"NOTICED_API_KEY\": \"nk_live_…\" }\n    }\n  }\n}\n```\n\n#### Cline (VS Code)\n\nEdit `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"noticed\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@noticed/cli\", \"mcp\"],\n      \"env\": { \"NOTICED_API_KEY\": \"nk_live_…\" }\n    }\n  }\n}\n```\n\n#### Continue\n\nMCP works in **agent mode** only. Add `.continue/mcpServers/noticed.yaml`:\n\n```yaml\nmcpServers:\n  - name: noticed\n    command: npx\n    args: [\"-y\", \"@noticed/cli\", \"mcp\"]\n    env:\n      NOTICED_API_KEY: nk_live_…\n```\n\n#### Zed\n\nEdit `~/.config/zed/settings.json` (note: key is `context_servers`, not `mcpServers`):\n\n```json\n{\n  \"context_servers\": {\n    \"noticed\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@noticed/cli\", \"mcp\"],\n      \"env\": { \"NOTICED_API_KEY\": \"nk_live_…\" }\n    }\n  }\n}\n```\n\n---\n\n## Agent Skill and plugin\n\nThe portable noticed Agent Skill works in Codex, Claude Code, Cursor, and other\nclients supported by the open [skills](https://skills.sh) ecosystem:\n\n```bash\n# Inspect the skill before installation\nnpx skills add noticedso/cli --list\n\n# Install globally for Codex and Claude Code\nnpx skills add noticedso/cli --skill noticed-search -g \\\n  --agent codex --agent claude-code -y\n```\n\nThe repository is also an Agent Plugins 1.0 package. It carries a portable\n`plugin.json`, `skills/`, and `mcp.json`, plus a Claude Code compatibility\nmanifest under `.claude-plugin/`. The MCP definition starts the version-pinned\nstdio server; configure `NOTICED_API_KEY` in the client environment or run\n`noticed config --set-key …` before querying production data.\n\nTo install the Claude Code compatibility plugin directly from source:\n\n```bash\ngit clone https://github.com/noticedso/cli ~/.claude/plugins/noticed\n# restart Claude Code\n```\n\n---\n\n## Quick start (CLI)\n\n```bash\n# 1. Mint an API key at https://www.noticed.so/dashboard/api-keys\n# 2. Configure credentials\nnoticed config --set-key nk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 3. Search your network\nnoticed search \"react developers\"\n\n# 4. Find the shortest path to a specific person\nnoticed path @sarahml\nnoticed path --li sarah-chen\n\n# 5. JSON output for scripting\nnoticed search \"frontend\" --json | jq '.hits[].github_login'\n```\n\n---\n\n## Authentication\n\nThe CLI authenticates with a Bearer API key. Mint one at `/dashboard/api-keys` — the secret is shown once at create time, so copy it immediately. Tokens look like `nk_live_…`, are rate-limited to 60 requests per minute per key, and can be revoked from the same page.\n\n---\n\n## CLI commands\n\n### `noticed search <query>`\n\nSearch your developer network for people, companies, skills, or topics.\n\n```bash\nnoticed search \"AI engineers\"                  # natural language\nnoticed search \"@sarahml\"                      # GitHub username\nnoticed search \"CTO at Vercel\"                 # job title + company\nnoticed search \"kubernetes\" --source github    # filter by source\nnoticed search \"react\" --limit 10 --json       # paginated JSON output\nnoticed search \"engineers\" --csv > out.csv     # CSV export\nnoticed search \"Sarah Chen\" --paths            # also fetch paths to top hits\n```\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `-l, --limit <n>` | Maximum results | 25 |\n| `-o, --offset <n>` | Pagination offset | 0 |\n| `-s, --source <src>` | Filter: `github` or `linkedin` | all |\n| `--sort <col:dir>` | Sort: `name:asc`, `company:desc` | none |\n| `-p, --paths` | Fetch shortest paths to the top 5 hits | off |\n| `-j, --json` | Output raw JSON | off |\n| `--csv` | Output as CSV | off |\n| `--no-color` | Disable colors | auto |\n\n### `noticed path [target]`\n\nFind the shortest connection path between you and a person.\n\n```bash\nnoticed path @sarahml             # by GitHub login\nnoticed path 12345                # by github_user_id\nnoticed path --li sarah-chen      # by LinkedIn username\nnoticed path @sarahml --json      # machine-readable\n```\n\nLogins are resolved via search before the path lookup. Pass `--li` to skip the search step and look up by LinkedIn username directly.\n\n### `noticed config`\n\n```bash\nnoticed config                     # show current config\nnoticed config --set-url <url>     # set API URL\nnoticed config --set-key <key>     # set API key\nnoticed config --show              # show current config\n```\n\nConfig is stored at `~/.config/noticed/config.json` (XDG-compliant).\n\n### `noticed mcp`\n\n```bash\nnoticed mcp                        # start MCP server over stdio\nnoticed mcp --log-level debug      # with debug logging on stderr\n```\n\n### `noticed completion <shell>`\n\n```bash\nnoticed completion bash >> ~/.bashrc\nnoticed completion zsh >> ~/.zshrc\nnoticed completion fish > ~/.config/fish/completions/noticed.fish\n```\n\n---\n\n## Environment variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `NOTICED_API_KEY` | API key minted at https://www.noticed.so/dashboard/api-keys | yes |\n| `NOTICED_API_URL` | Override the noticed instance URL. Defaults to `https://www.noticed.so` — only set this if you self-host | no |\n| `NOTICED_BASE_URL` | Alias for `NOTICED_API_URL` | no |\n\nPrecedence: CLI flags > environment variables > config file.\n\n---\n\n## MCP tools\n\nThe 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.\n\n| Tool | Description |\n|------|-------------|\n| `search` | Discover noticed capabilities by keyword and optional category. Returns names, descriptions, categories, and JSON parameter schemas. Call with no arguments to list everything. |\n| `execute` | Run a capability by exact name. Pass capability arguments in the `args` object. |\n\nExample client-side flow:\n\n```jsonc\n// 1. Find the right capability\ntools/call search { \"query\": \"missions\" }\n// → returns [{ name: \"list_missions\", parameters: {…}, … }, …]\n\n// 2. Run it\ntools/call execute { \"capability\": \"list_missions\", \"args\": {} }\n// → returns the user's missions\n```\n\nThe ~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.\n\nTest with the MCP Inspector:\n\n```bash\n# stdio\nnpx @modelcontextprotocol/inspector npx @noticed/cli mcp\n\n# hosted (Streamable HTTP) — set Authorization: Bearer <key> in the inspector UI\nnpx @modelcontextprotocol/inspector\n# URL: https://mcp.noticed.so/api/mcp\n```\n\nOr by hand against the stdio server:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":1,\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' | noticed mcp\necho '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":2}' | noticed mcp\n```\n\n---\n\n## Programmatic usage\n\n```ts\nimport { NoticedApiClient } from \"@noticed/cli\";\n\nconst client = new NoticedApiClient({\n  baseUrl: \"https://www.noticed.so\",\n  apiKey: \"nk_live_…\",\n});\n\nconst results = await client.search(\"AI engineers\", { limit: 10 });\nconst path = await client.path({ to: results.hits[0]?.github_user_id });\n\nconsole.log(results.hits, path);\n```\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\nnpm run lint\nnpm run check-types\n```\n\n---\n\n## Self-hosting noticed\n\nThe 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.\n\nIf you do run your own instance, set `NOTICED_API_URL` to its URL — everything else works the same:\n\n```bash\nexport NOTICED_API_URL=https://noticed.your-domain.com\nexport NOTICED_API_KEY=nk_live_…\nnoticed search \"AI engineers\"\n```\n\nThe source for the hosted service lives at https://github.com/noticedso/noticed.\n\n---\n\n## License\n\n[MIT](LICENSE) © noticed\n",
  "bytes": 13639,
  "sha": "3142460f891a711d00f6d183f7d57b95334e5d0f73f1a905576d3444066fd8a4",
  "repo_slug": "noticedso/cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_noticedso_cli_e711b411/readme"
}