@alice-type/cli 0.1.0-beta.0 → 0.1.0-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +80 -0
- package/dist/client.js +6 -3
- package/package.json +3 -3
package/README.md
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Alice Client
|
|
2
|
+
|
|
3
|
+
Search your Alice memories from a terminal, a script, or an MCP host. The npm package provides the `alice` CLI and an MCP server over stdio.
|
|
4
|
+
|
|
5
|
+
## Set up access
|
|
6
|
+
|
|
7
|
+
1. Install Node.js 22 or newer.
|
|
8
|
+
2. In Alice, open **Settings → Integration tokens** and create a token. Copy it when it appears. The token grants read-only memory access for seven days.
|
|
9
|
+
3. Set these variables in your shell or MCP host.
|
|
10
|
+
|
|
11
|
+
| Variable | Value |
|
|
12
|
+
| --------------- | ---------------------------------------------------------------- |
|
|
13
|
+
| `ALICE_API_URL` | The origin of your Alice API, such as `https://api.example.com`. |
|
|
14
|
+
| `ALICE_TOKEN` | The integration token created in Alice settings. |
|
|
15
|
+
|
|
16
|
+
Use a deployment with the Alice integration API enabled. The API origin uses HTTPS, or HTTP on a loopback address for local development. Store the token in your shell or MCP host's secret settings and revoke it from Alice settings when access is no longer needed.
|
|
17
|
+
|
|
18
|
+
## CLI
|
|
19
|
+
|
|
20
|
+
Run a search without a global install.
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
npx --yes @alice-type/cli@beta memory search "release notes" --json
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
For repeated use, install the package globally.
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
npm install --global @alice-type/cli@beta
|
|
30
|
+
alice --help
|
|
31
|
+
alice memory search "project handoff" --limit 5
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Pass `--start-at` and `--end-at` for an inclusive RFC 3339 time range. Use the response's `nextCursor` with the same query and filters to fetch another page. A null cursor marks the last page. The page limit defaults to 10 and accepts values from 1 to 20. `--json` emits compact JSON for scripts.
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
alice memory search "project handoff" \
|
|
38
|
+
--start-at 2026-01-01T00:00:00Z \
|
|
39
|
+
--end-at 2026-01-31T23:59:59Z \
|
|
40
|
+
--limit 5 --json
|
|
41
|
+
|
|
42
|
+
alice memory search "project handoff" \
|
|
43
|
+
--start-at 2026-01-01T00:00:00Z \
|
|
44
|
+
--end-at 2026-01-31T23:59:59Z \
|
|
45
|
+
--limit 5 --cursor "<next-cursor>" --json
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Search results contain `items` and `nextCursor`. Items include the memory ID, title, summary, observation time, and source type. A legacy memory with no recorded source type returns `unknown`.
|
|
49
|
+
|
|
50
|
+
## MCP
|
|
51
|
+
|
|
52
|
+
Add Alice to your MCP host as a local stdio server. This example shows a host that uses an `mcpServers` JSON configuration. Substitute your API origin and supply the token through the host's secret settings when supported.
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"mcpServers": {
|
|
57
|
+
"alice": {
|
|
58
|
+
"command": "npx",
|
|
59
|
+
"args": ["--yes", "@alice-type/cli@beta", "mcp"],
|
|
60
|
+
"env": {
|
|
61
|
+
"ALICE_API_URL": "https://api.example.com",
|
|
62
|
+
"ALICE_TOKEN": "<alice-integration-token>"
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
For a global installation, set the command to `alice` and the arguments to `["mcp"]`. Pin an exact npm version in a shared configuration for repeatable installs.
|
|
70
|
+
|
|
71
|
+
The server exposes the read-only `search_memories` tool. Provide a `query` and optionally `startAt`, `endAt`, `limit`, or `cursor`. For example, ask your host to search Alice for project handoff notes and return five matches.
|
|
72
|
+
|
|
73
|
+
## Troubleshooting
|
|
74
|
+
|
|
75
|
+
| Symptom | Check |
|
|
76
|
+
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
77
|
+
| HTTP 401 | Create a fresh integration token and update `ALICE_TOKEN` in the process running the CLI or MCP server. |
|
|
78
|
+
| HTTP 429 | Wait before retrying. Reduce the frequency of automated searches. |
|
|
79
|
+
| HTTP 503 | Confirm that the target Alice deployment has memory search enabled. |
|
|
80
|
+
| MCP host cannot start Alice | Confirm that the host can find Node.js and `npx`, or give it the path to the installed executable. |
|
package/dist/client.js
CHANGED
|
@@ -38,9 +38,12 @@ export const memorySearchResultSchema = z.object({
|
|
|
38
38
|
});
|
|
39
39
|
const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]"]);
|
|
40
40
|
function apiOrigin(value) {
|
|
41
|
-
const
|
|
42
|
-
if (!
|
|
43
|
-
|
|
41
|
+
const origin = value?.trim() ?? "";
|
|
42
|
+
if (!URL.canParse(origin)) {
|
|
43
|
+
throw new Error("Set ALICE_API_URL to the Alice API origin.");
|
|
44
|
+
}
|
|
45
|
+
const url = new URL(origin);
|
|
46
|
+
if (url.username ||
|
|
44
47
|
url.password ||
|
|
45
48
|
url.search ||
|
|
46
49
|
url.hash ||
|
package/package.json
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alice-type/cli",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.1.0-beta.1",
|
|
4
|
+
"description": "Alice Client CLI and MCP server for searching Alice memories",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|
|
7
7
|
"node": ">=22"
|
|
8
8
|
},
|
|
9
9
|
"repository": {
|
|
10
10
|
"type": "git",
|
|
11
|
-
"url": "git+https://github.com/Alice-Type/alice-
|
|
11
|
+
"url": "git+https://github.com/Alice-Type/alice-client.git"
|
|
12
12
|
},
|
|
13
13
|
"publishConfig": {
|
|
14
14
|
"access": "public"
|