@adaptiqai/mcp 0.0.0-stage → 0.1.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "adaptiqai",
+  "version": "0.1.1",
+  "description": "AdaptiqAI's knowledge and memory tools in Claude Code: search, use and save your collections in the conversation you are in.",
+  "author": {
+    "name": "AdaptiqAI",
+    "url": "https://adaptiqai.com"
+  },
+  "homepage": "https://adaptiqai.com",
+  "license": "UNLICENSED",
+  "keywords": ["adaptiqai", "knowledge", "memory"],
+  "mcpServers": {
+    "adaptiqai": {
+      "command": "/bin/sh",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/adaptiqai-mcp"]
+    }
+  }
+}

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# AdaptiqAI for Claude Code, Cline and any MCP app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Your AdaptiqAI knowledge and this conversation's memory, as tools for the
+agent: an MCP server, over stdio, on the AdaptiqAI core.
+
+## Install
+
+**Claude Code**
+
+```bash
+claude mcp add adaptiqai -- npx -y @adaptiqai/mcp
+```
+
+or install it as a Claude Code plugin from a marketplace that lists it (the
+package carries `.claude-plugin/plugin.json`). The plugin runs the server
+from the package with a Node.js 22 or newer: Claude Code itself needs none,
+and one started from the Dock often runs without a terminal's PATH, so
+`bin/adaptiqai-mcp` looks in PATH, then where Volta, fnm, asdf, mise,
+Homebrew and nvm put Node.js, or takes the one `ADAPTIQAI_NODE` names (in the
+`env` of Claude Code's settings). With none, the AdaptiqAI tools are missing
+and the agent is told why. The plugin starts it with `/bin/sh`, so on
+Windows add the server with `claude mcp add` as above.
+
+**Cline** (the CLI, 3.0.74)
+
+```bash
+cline mcp add adaptiqai --yes -- npx -y @adaptiqai/mcp
+```
+
+That writes `~/.cline/data/settings/cline_mcp_settings.json`:
+
+```json
+{ "mcpServers": { "adaptiqai": { "transport": { "type": "stdio", "command": "npx", "args": ["-y", "@adaptiqai/mcp"] } } } }
+```
+
+**Any other MCP app**: run `npx -y @adaptiqai/mcp` as a stdio server.
+
+## Sign in
+
+The server signs in with the first of these it finds. The app's own key
+comes first: knowledge has to be in the workspace the app's model reads.
+
+- **Nothing to do when the app runs on an AdaptiqAI key the server can
+  see.** Claude Code set up by the console (Connect to app's `adaptiq-claude`)
+  passes its environment on to the servers it starts, and the server uses the
+  key Claude Code runs on when `ANTHROPIC_BASE_URL` is AdaptiqAI's. Cline's
+  OpenRouter provider, pointed at AdaptiqAI, keeps its key in Cline's settings.
+- **A key**: `ADAPTIQAI_API_KEY` in the server's environment.
+- **In the browser**: `npx -y @adaptiqai/mcp login`, or simply ask the agent
+  for your knowledge: while the computer is signed out, the first tool call
+  opens the approval page and tells the agent the code.
+
+One browser sign-in serves every app on this computer. It is kept in
+`~/.config/adaptiq/mcp/` (under `XDG_CONFIG_HOME` when set), readable by you
+alone.
+`npx -y @adaptiqai/mcp status` says whether this computer is signed in, and
+`logout` signs it out.
+
+## What it does
+
+- **`adaptiq_knowledge`**: what this conversation uses; search your saved
+  knowledge; use or stop a collection here.
+- **`adaptiq_memory`**: how full the memory is; your saved collections; opens
+  Knowledge in the browser to tidy up. It can't keep a conversation private,
+  as the DeepSeek Harness and Pi plugins can: Claude Code and Cline send their
+  model requests themselves, so AdaptiqAI saves what they send.
+- **`adaptiq_create_knowledge`**: save material (text, files, links) as a
+  collection, only when you ask for it. The server checks the request
+  against your own messages in the conversation, as every AdaptiqAI plugin
+  does.
+
+Otherwise the tools, their words and their answers are the ones the DeepSeek
+Harness and Pi plugins have (`agentTools` in `@adaptiqai/core`).
+
+## Which conversation a call is in
+
+MCP has no conversation id, so the server reads each app where it keeps its
+own:
+
+| | Claude Code 2.1.308 | Cline 3.0.74 |
+|---|---|---|
+| What the app hands the server | `CLAUDE_CODE_SESSION_ID`, `CLAUDE_PROJECT_DIR` and its own environment; `_meta["claudecode/toolUseId"]` on every call | nothing (no id in the environment or `_meta`) |
+| What its model requests name | `x-claude-code-session-id`, the same id | body `session_id`, only on its OpenRouter provider |
+| How the server finds the call's conversation | the transcript (`~/.claude/projects/…/<id>.jsonl`) that holds the call's tool-use id: Claude Code keeps the server across `/clear` and `/resume`, so the starting id goes stale. An agent's call is in the agent's own transcript (`<id>/subagents/…/agent-<agent>.jsonl`), and is the session `<id>.<agent>`, as the gateway names an agent's requests; what an agent saves stays the chat's | the conversation whose messages file (`~/.cline/data/sessions/<id>/<id>.messages.json`) holds the call, not answered yet: Cline writes it there a few milliseconds before it makes it. Cline's hub runs every task in one process, so when two tasks make the same call at once, or no file holds it, the record started last before this server wins: Cline starts a server for each conversation |
+| What has to be true for it to reach the model | Claude Code on the AdaptiqAI gateway with `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` (the gateway names a chat only from `x-claude-code-request-class: main`) | Cline's OpenRouter provider with its base URL set to the AdaptiqAI gateway |
+
+When that is not so, every tool says why instead of attaching knowledge to a
+conversation the model never reads. An app other than these two names no
+conversation, so its tool calls are refused the same way.
+
+The transcript also holds your own messages, which `adaptiq_create_knowledge`
+checks its quote against. The server reads them on this computer, only when
+the agent saves knowledge, as far back as your last messages go, and keeps
+nothing of them.
+
+## Configuration
+
+| Variable | Default |
+|---|---|
+| `ADAPTIQAI_API_KEY` | none. Used when the app runs on no AdaptiqAI key the server can see; else the browser sign-in |
+| `ADAPTIQAI_API_BASE` | `https://api.adaptiqai.com` |
+| `ADAPTIQAI_CONSOLE_URL` | `https://memory.adaptiqai.com/memory` |
+| `ADAPTIQAI_NODE` | the plugin looks for a Node.js 22 or newer |
+
+## Development
+
+```bash
+pnpm install
+pnpm --filter @adaptiqai/mcp run build      # lib/index.js, one file with core bundled in
+pnpm --filter @adaptiqai/mcp run test
+claude mcp add adaptiqai-dev -- node "$PWD/packages/mcp/lib/index.js"
+```
+
+MCP over stdio is a few JSON-RPC methods (`initialize`, `ping`,
+`tools/list`, `tools/call`), written by hand in `src/rpc.ts` and
+`src/index.ts`: the server ships as one file with no dependencies. Claude
+Code 2.1.308 asks for `server/discover` (MCP 2026-07-28) first and falls back
+to `initialize` when the server does not know it, as this one does not.

package/bin/adaptiqai-mcp

@@ -0,0 +1,47 @@
+#!/bin/sh
+# The AdaptiqAI MCP server as the Claude Code plugin starts it, through
+# /bin/sh, so a package that lost its file modes still starts (npx runs
+# lib/index.js itself). Claude Code needs no Node.js of its own, and one
+# started from the Dock or a menu often runs without the PATH a terminal gets
+# from nvm, fnm, Volta, asdf, mise or Homebrew, so a Node.js 22 or newer is
+# looked for there too, or ADAPTIQAI_NODE names one. With none, the server
+# still answers, with no tools and instructions that say why: the agent can
+# tell the person, where a server that fails to start says nothing.
+root=$(cd "$(dirname "$0")/.." && pwd)
+
+usable() {
+  [ -n "$1" ] && [ -x "$1" ] && "$1" -e 'process.exit(+process.versions.node.split(".")[0] >= 22 ? 0 : 1)' >/dev/null 2>&1
+}
+
+if [ -n "${ADAPTIQAI_NODE:-}" ]; then
+  usable "$ADAPTIQAI_NODE" && exec "$ADAPTIQAI_NODE" "$root/lib/index.js" "$@"
+else
+  for node in "$(command -v node 2>/dev/null)" \
+    "${VOLTA_HOME:-$HOME/.volta}/bin/node" \
+    "${FNM_DIR:-$HOME/.local/share/fnm}/aliases/default/bin/node" \
+    "$HOME/Library/Application Support/fnm/aliases/default/bin/node" \
+    "$HOME/.asdf/shims/node" "$HOME/.local/share/mise/shims/node" \
+    /opt/homebrew/bin/node /usr/local/bin/node /usr/bin/node \
+    "${NVM_DIR:-$HOME/.nvm}"/versions/node/*/bin/node; do
+    usable "$node" && exec "$node" "$root/lib/index.js" "$@"
+  done
+fi
+
+reason='AdaptiqAI knowledge and memory are not available here: their MCP server needs Node.js 22 or newer on this computer, and the Claude Code plugin found none. When the person asks for AdaptiqAI knowledge or memory, tell them to install Node.js 22 or newer (nodejs.org), or to set ADAPTIQAI_NODE to one in the env of Claude Code'"'"'s settings, and then to start Claude Code again.'
+echo "adaptiqai-mcp: $reason" >&2
+while IFS= read -r line || [ -n "$line" ]; do
+  id=$(printf '%s\n' "$line" | sed -nE 's/.*"id":("[^"]*"|-?[0-9]+).*/\1/p')
+  # A notification has no id and gets no answer.
+  [ -n "$id" ] || continue
+  case $line in
+    *'"method":"initialize"'*)
+      version=$(printf '%s\n' "$line" | sed -nE 's/.*"protocolVersion":"([^"]*)".*/\1/p')
+      result="{\"protocolVersion\":\"${version:-2025-06-18}\",\"capabilities\":{\"tools\":{}},\"serverInfo\":{\"name\":\"adaptiqai\",\"title\":\"AdaptiqAI\",\"version\":\"0.0.0\"},\"instructions\":\"$reason\"}" ;;
+    *'"method":"tools/list"'*) result='{"tools":[]}' ;;
+    *'"method":"ping"'*) result='{}' ;;
+    *)
+      printf '{"jsonrpc":"2.0","id":%s,"error":{"code":-32601,"message":"Method not found"}}\n' "$id"
+      continue ;;
+  esac
+  printf '{"jsonrpc":"2.0","id":%s,"result":%s}\n' "$id" "$result"
+done