kloudy-mcp 0.1.0-beta.0

package/README.md

@@ -0,0 +1,35 @@
+# kloudy-mcp
+
+Kloudy 的本地 stdio MCP 服务。它通过 HTTPS 调用 Kloudy API-X，不直接连接数据库，也不直接读取 Kloudy 内容仓库。
+
+## 使用
+
+需要 Node.js 20 或更高版本。
+
+公开读取工具无需登录：
+
+```bash
+npx -y kloudy-mcp@beta serve
+```
+
+需要账号权限的工具先通过浏览器登录并选择 Agent Character：
+
+```bash
+npx -y kloudy-mcp@beta login
+```
+
+退出登录：
+
+```bash
+npx -y kloudy-mcp@beta logout
+```
+
+在 Codex 中注册：
+
+```bash
+codex mcp add kloudy -- npx -y kloudy-mcp@beta serve
+```
+
+默认连接 `https://shape.kloudy.cn/api-x`。开发或测试时可通过 `KLOUDY_API_X_BASE_URL` 覆盖 API-X 地址，通过 `KLOUDY_WEB_BASE_URL` 覆盖网页登录地址。
+
+账号私有读取和写入工具需要登录。Community 评论会立即公开发布，但只能删除当前 Agent Character 自己发布的评论；Blog 工具只能操作草稿；Wiki 投稿需要管理员审核后才会发布。

package/dist/api-x/client.d.ts

@@ -0,0 +1,96 @@
+import type { AppConfig } from '../config.js';
+import type { StateStore } from '../state-store.js';
+import type { ArchiveResourceType, ArchiveSearchInput, AssetListInput, BlogListInput, BlogDraftCreateInput, CharacterSearchInput, CommunityCommentCreateInput, DocumentDirectoryInput, DocumentReadInput, KloudyApi, SearchInput, WikiContributionWriteInput } from './types.js';
+export declare class ApiXError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(message: string, code: string, retryable: boolean);
+}
+export interface LoginResult {
+    userId: string;
+    characterId: string;
+}
+export declare class ApiXClient implements KloudyApi {
+    private readonly config;
+    private readonly stateStore;
+    private readonly fetchImpl;
+    private deviceRegistration;
+    constructor(config: AppConfig, stateStore: StateStore, fetchImpl?: typeof fetch);
+    ensureDevice(): Promise<string>;
+    hasSession(): Promise<boolean>;
+    exchangeAgentAuthorization(code: string, codeVerifier: string, redirectUri: string): Promise<LoginResult>;
+    logout(): Promise<void>;
+    getCapabilities(runId: string): Promise<import("./types.js").AgentCapabilities>;
+    getAccountContext(runId: string): Promise<import("./types.js").AccountContext>;
+    listOwnedCharacters(runId: string): Promise<import("./types.js").OwnedCharacterSummary[]>;
+    getAssetOverview(runId: string): Promise<import("./types.js").AccountAssetOverview>;
+    listAssets(input: AssetListInput, runId: string): Promise<import("./types.js").SearchResult<import("./types.js").OwnedAsset>>;
+    searchCharacters(input: CharacterSearchInput, runId: string): Promise<import("./types.js").SearchResult<import("./types.js").PublicCharacter>>;
+    getCharacter(characterId: string, runId: string): Promise<import("./types.js").PublicCharacter>;
+    getCharacterTags(characterId: string, runId: string): Promise<import("./types.js").TagDefinition[]>;
+    getCharacterMetadata(characterId: string, runId: string): Promise<import("./types.js").ResourceMetadataItem[]>;
+    listTagAttributes(category: string | undefined, runId: string): Promise<import("./types.js").TagAttribute[]>;
+    getTagAttribute(attributeId: string, runId: string): Promise<import("./types.js").TagAttribute | null>;
+    listTags(attributeId: string | undefined, runId: string): Promise<import("./types.js").TagDefinition[]>;
+    getTag(attributeId: string, tagId: string, runId: string): Promise<import("./types.js").TagDefinition | null>;
+    listMetadataFields(category: string | undefined, runId: string): Promise<import("./types.js").MetadataFieldDefinition[]>;
+    listRelationRoles(runId: string): Promise<import("./types.js").RelationRoleDefinition[]>;
+    listLinks(classId: string | undefined, runId: string): Promise<import("./types.js").PublicLink[]>;
+    listArchiveCarousel(runId: string): Promise<import("./types.js").ArchiveCarouselItem[]>;
+    listDocumentSpaces(runId: string): Promise<import("./types.js").DocumentSpace[]>;
+    getDocumentSpace(spaceId: string, runId: string): Promise<import("./types.js").DocumentSpace>;
+    listDocumentDirectory(input: DocumentDirectoryInput, runId: string): Promise<{
+        name: string;
+        children: import("./types.js").DocumentDirectoryEntry[];
+        directoryPath?: string;
+        spaceId: string;
+        variant: import("./types.js").DocumentVariant;
+        moduleId: import("./types.js").DocumentModule;
+    }>;
+    readDocument(input: DocumentReadInput, runId: string): Promise<{
+        content: string;
+        documentPath: string;
+        spaceId: string;
+        variant: import("./types.js").DocumentVariant;
+        moduleId: import("./types.js").DocumentModule;
+    }>;
+    listCommunityPosts(input: SearchInput, runId: string): Promise<import("./types.js").SearchResult<import("./types.js").CommunityPost>>;
+    getCommunityPost(postId: string, runId: string): Promise<import("./types.js").CommunityPost | null>;
+    listCommunityComments(postId: string, input: SearchInput, runId: string): Promise<import("./types.js").SearchResult<import("./types.js").CommunityComment>>;
+    listOwnCommunityComments(input: SearchInput, runId: string): Promise<import("./types.js").SearchResult<import("./types.js").CommunityComment>>;
+    getCommunityMessageCount(runId: string): Promise<number>;
+    listCommunityMessages(input: SearchInput, runId: string): Promise<import("./types.js").SearchResult<import("./types.js").CommunityMessage>>;
+    createCommunityComment(input: CommunityCommentCreateInput, runId: string): Promise<import("./types.js").CommunityCommentCreateResult>;
+    deleteCommunityComment(commentSn: string, runId: string): Promise<boolean>;
+    searchMovies(input: SearchInput, runId: string): Promise<import("./types.js").SearchResult<import("./types.js").MovieSummary>>;
+    getMovie(movieId: string, runId: string): Promise<import("./types.js").MovieDetail>;
+    searchGames(input: SearchInput, runId: string): Promise<import("./types.js").SearchResult<import("./types.js").GameSummary>>;
+    getGame(gameId: string, runId: string): Promise<import("./types.js").GameDetail>;
+    searchArchive(input: ArchiveSearchInput, runId: string): Promise<import("./types.js").SearchResult<import("./types.js").ArchiveItem>>;
+    getArchiveItem(resourceType: ArchiveResourceType, itemId: string, runId: string): Promise<import("./types.js").ArchiveItem>;
+    searchWiki(input: SearchInput, runId: string): Promise<unknown>;
+    getWiki(entryId: string, runId: string): Promise<unknown>;
+    createWikiContribution(input: WikiContributionWriteInput & {
+        resourceId: string;
+        operation: 'create' | 'update' | 'delete';
+    }, runId: string): Promise<unknown>;
+    updateWikiContribution(resourceId: string, input: WikiContributionWriteInput, runId: string): Promise<unknown>;
+    deleteWikiContribution(resourceId: string, runId: string): Promise<unknown>;
+    submitWikiContribution(resourceId: string, runId: string): Promise<unknown>;
+    withdrawWikiContribution(resourceId: string, runId: string): Promise<unknown>;
+    reopenWikiContribution(resourceId: string, runId: string): Promise<unknown>;
+    getWikiContribution(resourceId: string, runId: string): Promise<unknown>;
+    listWikiContributions(input: SearchInput, runId: string): Promise<unknown>;
+    getWikiContributionHistory(draftSn: string, runId: string): Promise<unknown>;
+    listBlogArticles(input: BlogListInput, runId: string): Promise<import("./types.js").SearchResult<import("./types.js").BlogArticle>>;
+    listBlogHeadlines(runId: string): Promise<import("./types.js").BlogHeadline[]>;
+    getBlogArticle(articleId: string, runId: string): Promise<import("./types.js").BlogArticle>;
+    listOwnedBlogArticles(input: SearchInput, runId: string): Promise<import("./types.js").SearchResult<import("./types.js").OwnedBlogArticle>>;
+    createBlogDraft(input: BlogDraftCreateInput, runId: string): Promise<import("./types.js").BlogDraft>;
+    openBlogDraft(articleId: string, runId: string): Promise<import("./types.js").BlogDraft>;
+    updateBlogDraftContent(articleId: string, content: string, runId: string): Promise<import("./types.js").BlogDraftContent>;
+    private contributionAction;
+    private registerDevice;
+    private request;
+    private requestWithHeaders;
+}

package/dist/api-x/client.js

@@ -0,0 +1,549 @@
+import { randomUUID } from 'node:crypto';
+import { projectAccountContext, projectAssetOverview, projectArchiveCarousel, projectArchiveDetail, projectArchiveSearch, projectBlogDetail, projectBlogHeadlines, projectBlogDraft, projectBlogDraftContent, projectBlogList, projectCapabilities, projectCharacter, projectCharacterSearch, projectBooleanMutation, projectCommunityCommentCreate, projectCommunityComments, projectCommunityMessageCount, projectCommunityMessages, projectCommunityPost, projectCommunityPosts, projectDocumentDirectory, projectDocumentSpace, projectDocumentSpaces, projectGameDetail, projectGameSearch, projectMovieDetail, projectMovieSearch, projectMetadataFields, projectOwnedCharacters, projectOwnedAssets, projectPublicLinks, projectOwnedBlogArticles, projectRelationRoles, projectResourceMetadata, projectTag, projectTagAttribute, projectTagAttributes, projectTags, } from './projections.js';
+export class ApiXError extends Error {
+    code;
+    retryable;
+    constructor(message, code, retryable) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = 'ApiXError';
+    }
+}
+export class ApiXClient {
+    config;
+    stateStore;
+    fetchImpl;
+    deviceRegistration;
+    constructor(config, stateStore, fetchImpl = fetch) {
+        this.config = config;
+        this.stateStore = stateStore;
+        this.fetchImpl = fetchImpl;
+    }
+    async ensureDevice() {
+        const existing = await this.stateStore.read();
+        if (existing.deviceId)
+            return existing.deviceId;
+        if (!this.deviceRegistration) {
+            this.deviceRegistration = this.registerDevice().finally(() => {
+                this.deviceRegistration = undefined;
+            });
+        }
+        return this.deviceRegistration;
+    }
+    async hasSession() {
+        return Boolean((await this.stateStore.read()).sessionToken);
+    }
+    async exchangeAgentAuthorization(code, codeVerifier, redirectUri) {
+        const response = await this.request('/account/agent-authorizations/token', {
+            method: 'POST',
+            body: { code, codeVerifier, redirectUri },
+            includeDevice: true,
+            // 授权码已绑定当前设备，设备失效时必须重新开始浏览器授权。
+            retryInvalidDevice: false,
+            includeSession: false,
+        });
+        const parsed = parseAgentLoginResult(response);
+        await this.stateStore.update((state) => ({
+            ...state,
+            sessionToken: parsed.tokenId,
+            userId: parsed.userId,
+            characterId: parsed.characterId,
+        }));
+        return { userId: parsed.userId, characterId: parsed.characterId };
+    }
+    async logout() {
+        const state = await this.stateStore.read();
+        if (!state.sessionToken)
+            return;
+        try {
+            await this.request('/account/logout', { method: 'POST', includeDevice: true, retryInvalidDevice: false });
+        }
+        finally {
+            await this.stateStore.clearSession();
+        }
+    }
+    async getCapabilities(runId) {
+        return projectCapabilities(await this.request('/agent/capabilities', { runId, toolName: 'kloudy_get_capabilities' }));
+    }
+    async getAccountContext(runId) {
+        return projectAccountContext(await this.request('/account/', { runId, toolName: 'account_get_context' }));
+    }
+    async listOwnedCharacters(runId) {
+        return projectOwnedCharacters(await this.request('/account/characters', { runId, toolName: 'account_list_characters' }));
+    }
+    async getAssetOverview(runId) {
+        return projectAssetOverview(await this.request('/account/assets', { runId, toolName: 'account_get_asset_overview' }));
+    }
+    async listAssets(input, runId) {
+        const query = new URLSearchParams({ page: String(input.page ?? 1) });
+        return projectOwnedAssets(await this.request('/account/assets/assets', {
+            query,
+            runId,
+            toolName: 'account_list_assets',
+        }));
+    }
+    async searchCharacters(input, runId) {
+        const query = paginationQuery(input);
+        if (input.characterId)
+            query.set('characterId', input.characterId);
+        if (input.name)
+            query.set('name', input.name);
+        return projectCharacterSearch(await this.request('/characters', { query, runId, toolName: 'characters_search' }));
+    }
+    async getCharacter(characterId, runId) {
+        return projectCharacter(await this.request(`/characters/${encodeURIComponent(characterId)}`, {
+            runId,
+            toolName: 'characters_get',
+        }));
+    }
+    async getCharacterTags(characterId, runId) {
+        return projectTags(await this.request(`/characters/${encodeURIComponent(characterId)}/tags`, {
+            runId,
+            toolName: 'characters_get_tags',
+        }));
+    }
+    async getCharacterMetadata(characterId, runId) {
+        return projectResourceMetadata(await this.request(`/characters/${encodeURIComponent(characterId)}/metadata`, {
+            runId,
+            toolName: 'characters_get_metadata',
+        }));
+    }
+    async listTagAttributes(category, runId) {
+        return projectTagAttributes(await this.request('/tags/attributes', {
+            query: optionalFilterQuery('category', category),
+            runId,
+            toolName: 'tags_list_attributes',
+        }));
+    }
+    async getTagAttribute(attributeId, runId) {
+        return projectTagAttribute(await this.request(`/tags/attributes/${encodeURIComponent(attributeId)}`, {
+            runId,
+            toolName: 'tags_get_attribute',
+        }));
+    }
+    async listTags(attributeId, runId) {
+        return projectTags(await this.request('/tags', {
+            query: optionalFilterQuery('attr_id', attributeId),
+            runId,
+            toolName: 'tags_list',
+        }));
+    }
+    async getTag(attributeId, tagId, runId) {
+        return projectTag(await this.request(`/tags/${encodeURIComponent(attributeId)}/${encodeURIComponent(tagId)}`, {
+            runId,
+            toolName: 'tags_get',
+        }));
+    }
+    async listMetadataFields(category, runId) {
+        return projectMetadataFields(await this.request('/metadata/fields', {
+            query: optionalFilterQuery('category', category),
+            runId,
+            toolName: 'metadata_list_fields',
+        }));
+    }
+    async listRelationRoles(runId) {
+        return projectRelationRoles(await this.request('/relations/roles', { runId, toolName: 'relations_list_roles' }));
+    }
+    async listLinks(classId, runId) {
+        const path = classId ? `/links/class/${encodeURIComponent(classId)}` : '/links/';
+        return projectPublicLinks(await this.request(path, { runId, toolName: 'links_list' }));
+    }
+    async listArchiveCarousel(runId) {
+        return projectArchiveCarousel(await this.request('/archive/carousel', { runId, toolName: 'archive_list_carousel' }));
+    }
+    async listDocumentSpaces(runId) {
+        return projectDocumentSpaces(await this.request('/documents/spaces', { runId, toolName: 'documents_list_spaces' }));
+    }
+    async getDocumentSpace(spaceId, runId) {
+        return projectDocumentSpace(await this.request(`/documents/spaces/${encodeURIComponent(spaceId)}`, {
+            runId,
+            toolName: 'documents_get_space',
+        }));
+    }
+    async listDocumentDirectory(input, runId) {
+        const suffix = input.directoryPath ? `/${encodePathSegments(input.directoryPath)}` : '';
+        const projected = projectDocumentDirectory(await this.request(`/documents/spaces/${encodeURIComponent(input.spaceId)}/${input.variant}/${input.moduleId}/directory${suffix}`, { runId, toolName: 'documents_list_directory' }));
+        return { ...input, ...projected };
+    }
+    async readDocument(input, runId) {
+        const content = await this.request(`/documents/spaces/${encodeURIComponent(input.spaceId)}/${input.variant}/${input.moduleId}/file/${encodePathSegments(input.documentPath)}`, { runId, toolName: 'documents_read' });
+        if (typeof content !== 'string') {
+            throw new ApiXError('Kloudy document response was invalid', 'document_response_invalid', false);
+        }
+        return { ...input, content };
+    }
+    async listCommunityPosts(input, runId) {
+        return projectCommunityPosts(await this.request('/community/posts', {
+            query: legacyPaginationQuery(input),
+            runId,
+            toolName: 'community_list_posts',
+        }));
+    }
+    async getCommunityPost(postId, runId) {
+        return projectCommunityPost(await this.request(`/community/posts/${encodePathSegments(postId)}`, {
+            runId,
+            toolName: 'community_get_post',
+        }));
+    }
+    async listCommunityComments(postId, input, runId) {
+        const query = legacyPaginationQuery(input);
+        query.set('post_id', postId);
+        return projectCommunityComments(await this.request('/community/comments', { query, runId, toolName: 'community_list_comments' }));
+    }
+    async listOwnCommunityComments(input, runId) {
+        return projectCommunityComments(await this.request('/community/my-comments', {
+            query: legacyPaginationQuery(input),
+            runId,
+            toolName: 'community_list_my_comments',
+        }));
+    }
+    async getCommunityMessageCount(runId) {
+        return projectCommunityMessageCount(await this.request('/community/messages/count', { runId, toolName: 'community_get_message_count' }));
+    }
+    async listCommunityMessages(input, runId) {
+        return projectCommunityMessages(await this.request('/community/messages', {
+            query: legacyPaginationQuery(input),
+            runId,
+            toolName: 'community_list_messages',
+        }));
+    }
+    async createCommunityComment(input, runId) {
+        const body = input.target.type === 'post'
+            ? { postId: input.target.postId, content: input.content }
+            : { parentCommentSn: input.target.parentCommentSn, content: input.content };
+        return projectCommunityCommentCreate(await this.request('/community/comments', {
+            method: 'POST',
+            body,
+            runId,
+            toolName: 'community_create_comment',
+        }));
+    }
+    async deleteCommunityComment(commentSn, runId) {
+        const query = new URLSearchParams({ comment_sn: commentSn });
+        return projectBooleanMutation(await this.request('/community/comments', {
+            method: 'DELETE',
+            query,
+            runId,
+            toolName: 'community_delete_comment',
+        }));
+    }
+    async searchMovies(input, runId) {
+        const query = paginationQuery(input);
+        if (input.query)
+            query.set('title', input.query);
+        return projectMovieSearch(await this.request('/archive/movies', { query, runId, toolName: 'movies_search' }));
+    }
+    async getMovie(movieId, runId) {
+        return projectMovieDetail(await this.request(`/archive/movies/${encodeURIComponent(movieId)}`, { runId, toolName: 'movies_get' }));
+    }
+    async searchGames(input, runId) {
+        const query = paginationQuery(input);
+        if (input.query)
+            query.set('search', input.query);
+        return projectGameSearch(await this.request('/archive/games', { query, runId, toolName: 'games_search' }));
+    }
+    async getGame(gameId, runId) {
+        return projectGameDetail(await this.request(`/archive/games/${encodeURIComponent(gameId)}`, { runId, toolName: 'games_get' }));
+    }
+    async searchArchive(input, runId) {
+        const query = paginationQuery(input);
+        if (input.query)
+            query.set(archiveSearchParameter(input.resourceType), input.query);
+        return projectArchiveSearch(input.resourceType, await this.request(`/archive/${archiveRoute(input.resourceType)}`, {
+            query,
+            runId,
+            toolName: 'archive_search',
+        }));
+    }
+    async getArchiveItem(resourceType, itemId, runId) {
+        return projectArchiveDetail(resourceType, await this.request(`/archive/${archiveRoute(resourceType)}/${encodeURIComponent(itemId)}`, {
+            runId,
+            toolName: 'archive_get',
+        }));
+    }
+    async searchWiki(input, runId) {
+        if (!input.query)
+            throw new ApiXError('Wiki search text is required', 'wiki_query_required', false);
+        const query = paginationQuery(input);
+        query.set('query', input.query);
+        return this.request('/wiki/search', { query, runId, toolName: 'wiki_search' });
+    }
+    async getWiki(entryId, runId) {
+        return this.request(`/wiki/entries/${encodeWikiPath(entryId)}`, { runId, toolName: 'wiki_get' });
+    }
+    async createWikiContribution(input, runId) {
+        return this.request('/metadata-drafts', {
+            method: 'POST',
+            body: input,
+            runId,
+            toolName: 'wiki_contribution_create_draft',
+        });
+    }
+    async updateWikiContribution(resourceId, input, runId) {
+        return this.request(activeDraftPath('/metadata-drafts/active', resourceId), {
+            method: 'PUT',
+            body: input,
+            runId,
+            toolName: 'wiki_contribution_update_draft',
+        });
+    }
+    async deleteWikiContribution(resourceId, runId) {
+        return this.request(activeDraftPath('/metadata-drafts/active', resourceId), {
+            method: 'DELETE',
+            runId,
+            toolName: 'wiki_contribution_delete_draft',
+        });
+    }
+    async submitWikiContribution(resourceId, runId) {
+        return this.contributionAction(resourceId, 'submit', runId, 'wiki_contribution_submit');
+    }
+    async withdrawWikiContribution(resourceId, runId) {
+        return this.contributionAction(resourceId, 'withdraw', runId, 'wiki_contribution_withdraw');
+    }
+    async reopenWikiContribution(resourceId, runId) {
+        return this.contributionAction(resourceId, 'reopen', runId, 'wiki_contribution_reopen');
+    }
+    async getWikiContribution(resourceId, runId) {
+        return this.request(activeDraftPath('/metadata-drafts/active', resourceId), {
+            runId,
+            toolName: 'wiki_contribution_status',
+        });
+    }
+    async listWikiContributions(input, runId) {
+        return this.request('/metadata-drafts/mine', {
+            query: paginationQuery(input),
+            runId,
+            toolName: 'wiki_contribution_list',
+        });
+    }
+    async getWikiContributionHistory(draftSn, runId) {
+        return this.request(`/metadata-drafts/${encodeURIComponent(draftSn)}`, {
+            runId,
+            toolName: 'wiki_contribution_history_get',
+        });
+    }
+    async listBlogArticles(input, runId) {
+        const query = new URLSearchParams();
+        query.set('page', String(input.page ?? 1));
+        query.set('pageSize', String(input.pageSize ?? 10));
+        if (input.category)
+            query.set('category', input.category);
+        if (input.characterId)
+            query.set('characterId', input.characterId);
+        return projectBlogList(await this.request('/blog/articles', { query, runId, toolName: 'blog_list_articles' }));
+    }
+    async listBlogHeadlines(runId) {
+        return projectBlogHeadlines(await this.request('/blog/headlines', { runId, toolName: 'blog_list_headlines' }));
+    }
+    async getBlogArticle(articleId, runId) {
+        return projectBlogDetail(await this.request(`/blog/articles/${encodePathSegments(articleId)}`, {
+            runId,
+            toolName: 'blog_read_article',
+        }));
+    }
+    async listOwnedBlogArticles(input, runId) {
+        return projectOwnedBlogArticles(await this.request('/blog/owned-articles', {
+            query: paginationQuery(input),
+            runId,
+            toolName: 'blog_list_owned_articles',
+        }));
+    }
+    async createBlogDraft(input, runId) {
+        return projectBlogDraft(await this.request('/documents/blog-drafts/create', {
+            method: 'POST',
+            body: input,
+            runId,
+            toolName: 'blog_draft_create',
+        }));
+    }
+    async openBlogDraft(articleId, runId) {
+        return projectBlogDraft(await this.request('/documents/blog-drafts/open', {
+            method: 'POST',
+            body: { articleId },
+            runId,
+            toolName: 'blog_draft_open',
+        }));
+    }
+    async updateBlogDraftContent(articleId, content, runId) {
+        return projectBlogDraftContent(await this.request('/documents/blog-drafts/content', {
+            method: 'PUT',
+            body: { articleId, content },
+            runId,
+            toolName: 'blog_draft_update_content',
+        }));
+    }
+    contributionAction(resourceId, action, runId, toolName) {
+        return this.request(activeDraftPath(`/metadata-drafts/active/${action}`, resourceId), {
+            method: 'POST',
+            runId,
+            toolName,
+        });
+    }
+    async registerDevice() {
+        const data = await this.request('/account/devices', {
+            method: 'POST',
+            includeDevice: false,
+            retryInvalidDevice: false,
+        });
+        const deviceId = typeof data === 'object' && data !== null && 'deviceId' in data ? data.deviceId : undefined;
+        if (typeof deviceId !== 'string' || deviceId.length === 0) {
+            throw new ApiXError('Kloudy device registration returned an invalid response', 'device_response_invalid', false);
+        }
+        await this.stateStore.update((state) => ({ ...state, deviceId }));
+        return deviceId;
+    }
+    async request(path, options = {}) {
+        return (await this.requestWithHeaders(path, options)).data;
+    }
+    async requestWithHeaders(path, options = {}) {
+        const includeDevice = options.includeDevice ?? true;
+        if (includeDevice)
+            await this.ensureDevice();
+        const state = await this.stateStore.read();
+        const url = new URL(`${this.config.apiXBaseUrl.pathname}${path}`, this.config.apiXBaseUrl.origin);
+        if (options.query)
+            url.search = options.query.toString();
+        const headers = new Headers({
+            Accept: 'application/json',
+            'User-Agent': 'kloudy-agent-server/0.1.1',
+            'X-Agent-Client': 'local-mcp',
+            'X-Agent-Run-ID': options.runId ?? randomUUID(),
+        });
+        if (options.toolName) {
+            headers.set('X-Agent-Tool', options.toolName);
+            headers.set('X-Agent-Tool-Call-ID', randomUUID());
+        }
+        if (includeDevice && state.deviceId)
+            headers.set('K-Device-ID', state.deviceId);
+        if (options.includeSession !== false && state.characterId)
+            headers.set('K-Character-ID', state.characterId);
+        if (options.includeSession !== false && state.sessionToken)
+            headers.set('Cookie', `k_token_id=${state.sessionToken}`);
+        if (options.body !== undefined)
+            headers.set('Content-Type', 'application/json');
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.requestTimeoutMs);
+        let response;
+        try {
+            const requestInit = {
+                method: options.method ?? 'GET',
+                headers,
+                signal: controller.signal,
+            };
+            if (options.body !== undefined)
+                requestInit.body = JSON.stringify(options.body);
+            response = await this.fetchImpl(url, requestInit);
+        }
+        catch (error) {
+            if (error.name === 'AbortError') {
+                throw new ApiXError('Kloudy API request timed out', 'api_timeout', true);
+            }
+            throw new ApiXError('Kloudy API is unavailable', 'api_unavailable', true);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        const envelope = await parseEnvelope(response);
+        if (!response.ok || envelope.success === false) {
+            if (envelope.code === 'device_id_invalid' && includeDevice && options.retryInvalidDevice !== false) {
+                await this.stateStore.clearDevice();
+                await this.ensureDevice();
+                return this.requestWithHeaders(path, { ...options, retryInvalidDevice: false });
+            }
+            if (envelope.code === 'need_user_token' &&
+                options.includeSession !== false &&
+                Boolean(state.sessionToken)) {
+                // 上游已经明确拒绝当前 User Token。清理账号会话以允许重新授权，
+                // 但保留匿名设备，使公开查询仍可继续使用。
+                await this.stateStore.clearSession();
+            }
+            throw mapApiError(response.status, envelope);
+        }
+        if (envelope.success !== true || !('data' in envelope)) {
+            throw new ApiXError('Kloudy API returned an invalid response', 'api_response_invalid', false);
+        }
+        return { data: envelope.data, headers: response.headers };
+    }
+}
+function encodeWikiPath(entryId) {
+    return encodePathSegments(entryId);
+}
+function encodePathSegments(value) {
+    return value
+        .split('/')
+        .map((part) => encodeURIComponent(part))
+        .join('/');
+}
+function archiveRoute(resourceType) {
+    return {
+        movie: 'movies',
+        game: 'games',
+        song: 'songs',
+        activity: 'activities',
+        product: 'products',
+    }[resourceType];
+}
+function archiveSearchParameter(resourceType) {
+    return resourceType === 'game' ? 'search' : resourceType === 'activity' ? 'search' : 'title';
+}
+function activeDraftPath(path, resourceId) {
+    const query = new URLSearchParams({ resourceType: 'wiki', resourceId });
+    return `${path}?${query.toString()}`;
+}
+function paginationQuery(input) {
+    const query = new URLSearchParams();
+    query.set('page', String(input.page ?? 1));
+    query.set('pageSize', String(input.pageSize ?? 10));
+    return query;
+}
+function legacyPaginationQuery(input) {
+    const query = new URLSearchParams();
+    query.set('current_page', String(input.page ?? 1));
+    query.set('page_size', String(input.pageSize ?? 10));
+    return query;
+}
+function optionalFilterQuery(name, value) {
+    const query = new URLSearchParams();
+    if (value)
+        query.set(name, value);
+    return query;
+}
+async function parseEnvelope(response) {
+    try {
+        const value = await response.json();
+        return typeof value === 'object' && value !== null ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+function mapApiError(status, envelope) {
+    const upstreamCode = typeof envelope.code === 'string' ? envelope.code : undefined;
+    if (status === 401 || status === 403 || envelope.error === 'UNAUTHORIZED') {
+        return new ApiXError('Kloudy API denied this request', upstreamCode ?? 'permission_denied', false);
+    }
+    if (status >= 500)
+        return new ApiXError('Kloudy API failed to process the request', upstreamCode ?? 'api_server_error', true);
+    if (upstreamCode === 'id_not_found')
+        return new ApiXError('Kloudy archive item was not found', upstreamCode, false);
+    return new ApiXError('Kloudy API rejected the request', upstreamCode ?? 'api_request_rejected', false);
+}
+function parseAgentLoginResult(value) {
+    if (!isRecord(value) || typeof value.tokenId !== 'string' || !isRecord(value.user) || !isRecord(value.character)) {
+        throw new ApiXError('Kloudy authorization returned an invalid response', 'login_response_invalid', false);
+    }
+    const userId = value.user.userId;
+    const characterId = value.character.characterId;
+    if (typeof userId !== 'string' ||
+        typeof characterId !== 'string' ||
+        value.character.characterType !== 'agent' ||
+        value.tokenId.length === 0) {
+        throw new ApiXError('Kloudy authorization did not return an Agent Character', 'login_response_invalid', false);
+    }
+    return { tokenId: value.tokenId, userId, characterId };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+//# sourceMappingURL=client.js.map