@henrikogard/auroradocs-mcp 0.2.0 → 0.3.0

package/README.md

@@ -4,12 +4,14 @@
 granted AuroraCloud workspaces. It runs on your computer over stdio and sends
 authenticated requests to `https://api.auroradocs.eu`.
 
-The public package is `@henrikogard/auroradocs-mcp`, the executable is
-`aurora-mcp`, and this documentation targets version `0.2.0`.
+The public package is `@henrikogard/auroradocs-mcp` and the executable is
+`aurora-mcp`. The latest published package and current source version are
+`0.3.0`.
 
 For an end-to-end installation walkthrough, use the dedicated
-[Setup guide](docs/setup.md). Hermes and OpenClaw users should also apply the
-bounded [read-only agent profiles](docs/agent-profiles.md).
+[Setup guide](docs/setup.md). AI assistants and client integrators should start
+with the [Agent guide](docs/agent-guide.md); Hermes and OpenClaw users should
+also apply the bounded [read-only agent profiles](docs/agent-profiles.md).
 
 ## Requirements
 
@@ -17,10 +19,13 @@ bounded [read-only agent profiles](docs/agent-profiles.md).
 - an AuroraDocs account with an AuroraCloud-backed workspace
 - permission to create an MCP token for that workspace
 - a supported local MCP client: Claude Desktop, Claude Code, Codex, or another
-  client that can start a stdio server
+  client that can start a stdio server. Claude Desktop can also install the
+  `.mcpb` bundle from this repository instead of editing JSON.
 
-Browser-only workspaces and Local folders workspaces are not supported. The
-server does not read a browser tab or a folder on your computer.
+Browser-only workspaces and Local folders workspaces are not AuroraCloud MCP
+destinations. By default the server does not read a browser tab or local
+folder. The optional Obsidian importer reads only one explicitly configured
+vault root for analysis and import; it never turns that folder into a workspace.
 
 ## Create an MCP credential
 
@@ -64,6 +69,8 @@ write scope does not imply its read counterpart.
 | Update task metadata after confirmation | `read:objects`, `read:tasks`, `write:tasks`, `write:objects` |
 | Create or rename non-task objects | `read:objects`, `write:objects` |
 | Replace or append document content | `read:objects`, `read:content`, `write:content` |
+| Design custom types and reusable templates | `read:objects`; add `write:objects` and `write:content` only for an approved apply |
+| Import an authorized Obsidian vault | `read:objects`, `write:objects`, `write:content` |
 
 `read:objects` is the practical baseline because the server verifies workspace
 membership at startup and most tools operate on object metadata. Add
@@ -82,7 +89,7 @@ in the knowledge-search recipe above.
 ## Configure a client
 
 All examples below use the production AuroraCloud API, a new client credential,
-and package version `0.2.0`. Replace `REDACTED` locally. Do not commit the
+and package version `0.3.0`. Replace `REDACTED` locally. Do not commit the
 resulting configuration. The examples store the token in the client's saved
 configuration, so protect that file as a credential.
 
@@ -92,6 +99,8 @@ New client credentials require these environment variables:
 | --- | --- |
 | `AURORA_API_URL` | `https://api.auroradocs.eu` |
 | `AURORA_API_TOKEN` | the one-time `aur_mcp_client_` credential |
+| `AURORA_OBSIDIAN_VAULT_ROOT` | optional absolute path authorizing read-only analysis of one Obsidian vault |
+| `AURORA_MCP_STATE_DIR` | optional private plan/journal directory outside that vault |
 
 Do not set `AURORA_WORKSPACE_ID` for a client credential. The server discovers
 only its owner-approved grants with `list_workspaces`; each data call then
@@ -103,15 +112,22 @@ MCP-token authentication only.
 
 ### Claude Desktop
 
-Open Claude Desktop's developer settings and edit its MCP configuration. Add
-this server under `mcpServers`, preserving any servers already present:
+For one-click install, pack `auroradocs.mcpb` with `pnpm pack:mcpb` and install
+it from Claude Desktop **Settings → Extensions → Advanced settings → Install
+Extension…**. The extension asks for the AuroraCloud API URL and the MCP token
+(the token is stored in the OS keychain). Optional fields authorize one Obsidian
+vault and a private plan/journal directory.
+
+To configure it by hand, open Claude Desktop's developer settings and edit its
+MCP configuration. Add this server under `mcpServers`, preserving any servers
+already present:
 
 ```json
 {
   "mcpServers": {
     "auroradocs": {
       "command": "npx",
-      "args": ["-y", "@henrikogard/auroradocs-mcp@0.2.0"],
+      "args": ["-y", "@henrikogard/auroradocs-mcp@0.3.0"],
       "env": {
         "AURORA_API_URL": "https://api.auroradocs.eu",
         "AURORA_API_TOKEN": "REDACTED"
@@ -134,7 +150,7 @@ Options must appear before the server name:
 claude mcp add --transport stdio --scope user \
   --env AURORA_API_URL=https://api.auroradocs.eu \
   --env AURORA_API_TOKEN=REDACTED \
-  auroradocs -- npx -y @henrikogard/auroradocs-mcp@0.2.0
+  auroradocs -- npx -y @henrikogard/auroradocs-mcp@0.3.0
 ```
 
 Run `claude mcp get auroradocs` to inspect the saved entry, then use `/mcp` in
@@ -149,7 +165,7 @@ The installed Codex CLI accepts `--env` for local stdio servers:
 codex mcp add \
   --env AURORA_API_URL=https://api.auroradocs.eu \
   --env AURORA_API_TOKEN=REDACTED \
-  auroradocs -- npx -y @henrikogard/auroradocs-mcp@0.2.0
+  auroradocs -- npx -y @henrikogard/auroradocs-mcp@0.3.0
 ```
 
 Run `codex mcp get auroradocs` to inspect the saved entry.
@@ -161,7 +177,7 @@ Use this valid generic JSON shape when a client accepts an MCP server object:
 ```json
 {
   "command": "npx",
-  "args": ["-y", "@henrikogard/auroradocs-mcp@0.2.0"],
+  "args": ["-y", "@henrikogard/auroradocs-mcp@0.3.0"],
   "env": {
     "AURORA_API_URL": "https://api.auroradocs.eu",
     "AURORA_API_TOKEN": "REDACTED"
@@ -173,6 +189,56 @@ The client must launch the process locally and communicate over stdio. Do not
 configure `https://api.auroradocs.eu` as an MCP HTTP/SSE URL; it is the API the
 local server calls, not a hosted MCP endpoint.
 
+## Agent discovery and recovery
+
+The server sends initialization instructions, exposes machine-readable workflow
+recipes with approval/write/stop/result contracts, and advertises MCP
+completions for authorized workspace, project, object-type, recipe, and template
+prompt/resource arguments. The `template_instantiation` prompt guides an exact
+template selection before creation. `restore_object` recovers an explicitly
+identified soft-deleted object and safely reports when it was already active.
+
+MCP completions apply to prompt and resource-template arguments; direct tool
+inputs continue to use the bounded discovery tools documented in the
+[Agent guide](docs/agent-guide.md).
+
+## Custom databases and templates
+
+AuroraDocs MCP can discover existing object types/templates, offer starter
+recipes for contacts, interests, equipment, subscriptions, and expenses, and
+plan an arbitrary special-purpose schema. Use `plan_custom_database` first,
+review the exact plan ID/hash, then call `apply_custom_database_plan` only after
+approval. Updates are additive: they cannot remove a property, change its value
+type or storage mapping, weaken requiredness, or silently retarget relations.
+
+The `custom_database_design` prompt teaches the same recipe-first,
+plan-before-apply flow. Templates can include a starter body and schema-declared
+defaults, but should never contain real credentials, payment data, or sensitive
+personal records.
+
+## Obsidian vault import
+
+Set `AURORA_OBSIDIAN_VAULT_ROOT` to one absolute local vault path only when you
+want to authorize read-only analysis. Import is a separate action: the server
+first returns a reviewable plan, then asks through MCP form elicitation when the
+client supports it. A compatibility client must wait for a later user message
+and send the exact plan ID/hash with `confirmed: true`. Decline, cancel,
+malformed confirmation, stale source state, missing scopes, viewer access, and
+E2EE all stop before AuroraDocs writes.
+
+Imports run in resume-safe batches, keep private plan metadata plus a
+content-free progress journal outside the vault, survive MCP process restarts,
+and never modify the source. Custom-database plans use the same private state
+directory. `list_workspaces` re-reads the current grant set from AuroraCloud, so
+a new or revoked grant is visible without restarting the MCP process. Back up
+both systems first and start with a small test workspace. See
+[Obsidian import](docs/obsidian-import.md) for configuration, mapping, consent,
+recovery, and fidelity limits.
+
+Analysis rejects more than 256 MiB of eligible Markdown/Canvas source files,
+and hidden, plugin, Git, cache, trash, and other ignored paths cannot be read as
+attachments even when vault content links to them.
+
 ## Verify read-only access first
 
 1. Grant the client one workspace with only `read:objects`.
@@ -207,7 +273,8 @@ the old token. Tokens cannot be extended or recovered.
 ## Security model
 
 - The MCP protocol process is local and stdio-only; AuroraDocs does not provide
-  a hosted MCP HTTP, SSE, or OAuth endpoint.
+  a hosted MCP HTTP, SSE, or OAuth endpoint. The server speaks MCP 2026-07-28
+  and still serves 2025-era stdio clients.
 - AuroraCloud checks workspace membership, token scopes, the member's current
   role, expiry, revocation, rate limits, and audit events on requests.
 - E2EE content that is locked or unavailable is reported that way. The server
@@ -220,7 +287,9 @@ report a vulnerability, follow [SECURITY.md](SECURITY.md).
 
 ## Reference
 
+- [Agent guide](docs/agent-guide.md)
 - [Tools and scopes](docs/tools.md)
+- [Obsidian import](docs/obsidian-import.md)
 - [Hermes and OpenClaw agent profiles](docs/agent-profiles.md)
 - [Agent planning and knowledge roadmap](docs/agent-planning-knowledge-roadmap.md)
 - [Security boundaries](docs/security.md)

package/dist/auroraClient.d.ts

@@ -6,6 +6,7 @@
  * Tool execution resolves a granted or verified workspace before data access.
  */
 import type { AuroraConnectionContext, ContentReadResult, GrantedWorkspace } from './contracts.js';
+import type { CustomDatabaseTemplateDefault, ObjectTypeDef, ObjectTypeSchema, PropertyValueType } from './customDatabases.js';
 export type AuroraObjectRecord = {
     id: string;
     workspace_id: string;
@@ -34,6 +35,15 @@ export type AuroraPropertyRecord = {
     value_bool: boolean | null;
     value_ref: string | null;
 };
+export type AuroraTemplateInput = {
+    workspaceId: string;
+    objectId?: string;
+    type: string;
+    title: string;
+    icon?: string | null;
+    body?: string;
+    defaults?: CustomDatabaseTemplateDefault[];
+};
 export type AuroraWorkspaceMember = {
     id: string;
     name: string | null;
@@ -69,7 +79,7 @@ export type WorkspaceKnowledgeSource = {
     snippet: string | null;
     plainText: string | null;
     blockId: string | null;
-    updatedAt: string;
+    updatedAt: string | null;
     score: number | null;
     matchedFields: Array<'title' | 'content' | 'properties' | 'relationships'>;
     availability: WorkspaceKnowledgeAvailability;
@@ -117,6 +127,8 @@ type BackendClient = {
     request<T = unknown>(path: string, options?: {
         method?: string;
         body?: unknown;
+        rawBody?: BodyInit;
+        headers?: HeadersInit;
     }): Promise<T>;
 };
 export declare function resetAuroraClientForTests(): void;
@@ -133,12 +145,99 @@ export declare function listGrantedWorkspaces(): Promise<GrantedWorkspace[]>;
 export declare function authenticate(): Promise<void>;
 export declare function authenticate(options: AuthenticateOptions): Promise<AuroraConnectionContext>;
 export declare function listObjects(workspaceId: string, type?: string): Promise<AuroraObjectRecord[]>;
-export declare function listObjectsPage(workspaceId: string, type: string | undefined, page: number, perPage: number): Promise<CollectionPage<AuroraObjectRecord>>;
+export declare function listObjectsPage(workspaceId: string, type: string | undefined, page: number, perPage: number, options?: {
+    excludeTemplates?: boolean;
+}): Promise<CollectionPage<AuroraObjectRecord>>;
 export declare function searchObjectsPage(workspaceId: string, query: string, limit: number): Promise<WorkspaceKnowledgeSource[]>;
 export declare function getObject(id: string, workspaceId: string): Promise<AuroraObjectRecord | null>;
-export declare function createObject(workspaceId: string, type: string, title: string): Promise<AuroraObjectRecord>;
+export declare function createObject(workspaceId: string, type: string, title: string, options?: {
+    id?: string;
+    icon?: string | null;
+    parentId?: string | null;
+    isTemplate?: boolean;
+}): Promise<AuroraObjectRecord>;
+export declare function createAuroraObjectStable(workspaceId: string, input: {
+    id: string;
+    type: string;
+    title: string;
+    icon?: string | null;
+    parentId?: string | null;
+    isTemplate?: boolean;
+}): Promise<AuroraObjectRecord>;
+export declare function listAuroraObjectTypes(workspaceId: string): Promise<ObjectTypeDef[]>;
+export declare function createAuroraObjectType(workspaceId: string, input: {
+    id: string;
+    name: string;
+    icon: string | null;
+    color: string | null;
+    schema: ObjectTypeSchema[];
+}): Promise<ObjectTypeDef>;
+export declare function updateAuroraObjectType(workspaceId: string, id: string, changes: {
+    name?: string;
+    icon?: string | null;
+    color?: string | null;
+    schema?: ObjectTypeSchema[];
+}): Promise<ObjectTypeDef>;
+export declare function listAuroraTemplates(workspaceId: string, type?: string): Promise<AuroraObjectRecord[]>;
+export declare function listAuroraTemplatesPage(workspaceId: string, type?: string): Promise<CollectionPage<AuroraObjectRecord>>;
+export declare function upsertAuroraPropertyStable(objectId: string, workspaceId: string, key: string, valueType: PropertyValueType, value: string | number | boolean | null): Promise<void>;
+export declare function createAuroraTemplate(input: AuroraTemplateInput): Promise<AuroraObjectRecord>;
+export declare function createAuroraObjectFromTemplate(workspaceId: string, templateId: string, objectId?: string): Promise<string>;
+export declare function setAuroraContentStable(workspaceId: string, objectId: string, content: Record<string, unknown>): Promise<void>;
+export type AuroraImportCapabilities = {
+    workspaceId: string;
+    role: string;
+    scopes: string[];
+    e2ee: {
+        enabled: boolean;
+        importBlocked: boolean;
+        reason: string | null;
+    };
+    upload: {
+        maxBytes: number;
+        mimePolicy: unknown;
+        limitBytes: number;
+        usedBytes: number;
+        remainingBytes: number;
+    };
+    storage: {
+        available: boolean;
+        backend: string;
+    };
+};
+export declare function getAuroraImportCapabilities(workspaceId: string): Promise<AuroraImportCapabilities>;
+export type AuroraAttachmentUpload = {
+    id: string;
+    workspaceId: string;
+    objectId: string;
+    fileName: string;
+    mimeType: string;
+    sizeBytes: number;
+    url: string;
+};
+export declare function uploadAuroraMcpAttachment(input: {
+    workspaceId: string;
+    objectId: string;
+    fileName: string;
+    mimeType: string;
+    bytes: Buffer;
+    idempotencyKey: string;
+}): Promise<AuroraAttachmentUpload>;
 export declare function updateObjectTitle(id: string, title: string, workspaceId: string): Promise<void>;
 export declare function deleteObject(id: string, workspaceId: string): Promise<void>;
+export declare function restoreObject(id: string, workspaceId: string): Promise<boolean>;
+/** Sentinel returned by getContent when content is E2EE-encrypted. */
+export declare const E2EE_LOCKED_SENTINEL = "<<E2EE_LOCKED>>";
+/**
+ * Read an object's content as plain text.
+ *
+ * Returns distinct availability states:
+ *   - `not_found` — the object does not exist in this workspace
+ *   - `empty` — the object exists but has no content record or empty content
+ *   - `encrypted_locked` — content is end-to-end encrypted (cannot be read)
+ *   - `permission_denied` — the token lacks `read:content` scope
+ *   - `available` — content was read successfully
+ */
 export declare function getContent(objectId: string, workspaceId: string): Promise<ContentReadResult>;
 export declare function getContentJson(objectId: string, workspaceId: string): Promise<Record<string, unknown> | null>;
 export declare function searchWorkspaceKnowledgeServer(workspaceId: string, query: string, limit?: number): Promise<WorkspaceKnowledgeSource[]>;
@@ -146,12 +245,22 @@ export declare function getWorkspaceKnowledgeObjectServer(workspaceId: string, o
 export declare function listWorkspaceRelatedKnowledgeServer(workspaceId: string, objectId: string, limit?: number): Promise<WorkspaceKnowledgeSource[]>;
 export declare function listWorkspaceRecentKnowledgeServer(workspaceId: string, limit?: number): Promise<WorkspaceKnowledgeSource[]>;
 export declare function setContent(objectId: string, workspaceId: string, contentJson: Record<string, unknown>): Promise<void>;
+/**
+ * Check whether an object's content is E2EE-encrypted, without fetching the
+ * full content payload. Returns `null` if the object or its content record
+ * is missing. Used to pre-check before mixed write operations (e.g. updating
+ * both title and content) so the operation fails atomically instead of
+ * leaving a half-applied update.
+ */
+export declare function getObjectE2eeStatus(objectId: string, workspaceId: string): Promise<boolean | null>;
 export declare function appendContentText(objectId: string, workspaceId: string, text: string): Promise<void>;
-export declare function listProperties(objectIds: string[], workspaceId: string): Promise<AuroraPropertyRecord[]>;
+export declare function listProperties(objectIds: string[], workspaceId: string, options?: {
+    maxPages?: number;
+}): Promise<AuroraPropertyRecord[]>;
 export declare function upsertProperty(objectId: string, workspaceId: string, key: string, valueType: string, value: string): Promise<void>;
 export declare function listMembers(workspaceId: string): Promise<AuroraWorkspaceMember[]>;
 export declare function listTaskLists(workspaceId: string): Promise<AuroraTaskList[]>;
-export declare function listTaskStatuses(_workspaceId: string): Promise<string[]>;
+export declare function listTaskStatuses(): Promise<string[]>;
 export type AuroraTaskProps = {
     status: string | null;
     priority: string | null;
@@ -162,12 +271,16 @@ export type AuroraTaskProps = {
     task_list_id: string | null;
 };
 export declare function getTaskProps(objectId: string, workspaceId: string): Promise<AuroraTaskProps>;
-export declare function updateTaskProps(objectId: string, workspaceId: string, patch: Partial<AuroraTaskProps>): Promise<void>;
+export declare function updateTaskProps(objectId: string, workspaceId: string, patch: Partial<AuroraTaskProps>, options?: {
+    existingObject?: AuroraObjectRecord;
+}): Promise<void>;
 export type AuroraPlanningTask = AuroraTaskProps & {
     id: string;
     title: string | null;
     updated_at: string | null;
 };
+/** Maximum number of tasks listPlanningTasks will fetch + hydrate. */
+export declare const PLANNING_TASKS_MAX = 500;
 export declare function listPlanningTasks(workspaceId: string): Promise<AuroraPlanningTask[]>;
 export declare function readCanvasContent(workspaceId: string, objectId: string): Promise<{
     object: AuroraObjectRecord;