@mcohenchen/pingcode-mcp 0.0.0-stage → 0.3.2

package/dist/pjm/index.js

@@ -0,0 +1,275 @@
+import { PingCodeError } from "../client/errors.js";
+import { HOST_PREFIX_RE, LONG_ID_RE, SCHEME_RE, decode } from "../client/refs.js";
+/** True when the work item is not in a completed state (pending / in_progress / …). */
+export function isIncompleteWorkItem(w) {
+    return (w.state?.type ?? "") !== "completed";
+}
+function summarizeDescription(description) {
+    if (description == null || description === "")
+        return null;
+    if (typeof description === "string")
+        return description.slice(0, 500);
+    if (typeof description === "object") {
+        const o = description;
+        const raw = o.content ?? o.markdown ?? o.text ?? o.body ?? o.html;
+        if (typeof raw === "string" && raw.trim())
+            return raw.slice(0, 500);
+        const s = JSON.stringify(description);
+        return s === "{}" || s === "null" ? null : s.slice(0, 500);
+    }
+    return String(description).slice(0, 500);
+}
+export function summarizeWorkItem(w) {
+    const assigneeUser = w?.assignee?.user ?? w?.assignee;
+    return {
+        id: w.id,
+        identifier: w.identifier,
+        short_id: w.short_id,
+        title: w.title,
+        type: w.type,
+        state: w.state ? { name: w.state.name, type: w.state.type } : null,
+        assignee: assigneeUser
+            ? { id: assigneeUser.id, name: assigneeUser.display_name ?? assigneeUser.name }
+            : null,
+        sprint: w.sprint ? { id: w.sprint.id, name: w.sprint.name, status: w.sprint.status } : null,
+        project: w.project
+            ? { id: w.project.id, identifier: w.project.identifier, name: w.project.name }
+            : null,
+        html_url: w.html_url,
+        description_summary: summarizeDescription(w.description),
+    };
+}
+/** Parse a project identifier/id or a PJM project / sprint / board URL. */
+export function parseProjectRef(input) {
+    const s = input.trim();
+    if (!s)
+        throw new PingCodeError("project 不能为空");
+    let host;
+    let pathname = s;
+    if (SCHEME_RE.test(s) || HOST_PREFIX_RE.test(s)) {
+        try {
+            const u = new URL(SCHEME_RE.test(s) ? s : `https://${s}`);
+            host = u.host.toLowerCase() || undefined;
+            pathname = u.pathname;
+        }
+        catch {
+            throw new PingCodeError(`无法解析 URL: ${input}`);
+        }
+    }
+    else {
+        pathname = s.replace(/[?#].*$/, "");
+    }
+    const m = pathname.match(/\/pjm\/projects\/([^/?#]+)/i) || pathname.match(/\/projects\/([^/?#]+)/i);
+    if (m) {
+        const seg = decode(m[1]);
+        const ref = LONG_ID_RE.test(seg) ? { projectId: seg } : { projectIdentifier: seg };
+        if (host)
+            ref.host = host;
+        const sp = pathname.match(/\/sprints\/([^/?#]+)/i);
+        if (sp)
+            ref.sprintRef = decode(sp[1]);
+        return ref;
+    }
+    if (!host && LONG_ID_RE.test(s))
+        return { projectId: s };
+    if (!host && /^[A-Za-z][A-Za-z0-9_-]*$/.test(s))
+        return { projectIdentifier: s };
+    throw new PingCodeError(`无法从输入中解析项目: ${input}`);
+}
+/** Parse a work-item identifier/id/short_id or a PJM work-item URL. */
+export function parseWorkItemRef(input) {
+    const s = input.trim();
+    if (!s)
+        throw new PingCodeError("工作项标识不能为空");
+    let host;
+    let pathname = s;
+    if (SCHEME_RE.test(s) || HOST_PREFIX_RE.test(s)) {
+        try {
+            const u = new URL(SCHEME_RE.test(s) ? s : `https://${s}`);
+            host = u.host.toLowerCase() || undefined;
+            pathname = u.pathname;
+        }
+        catch {
+            throw new PingCodeError(`无法解析 URL: ${input}`);
+        }
+    }
+    else {
+        pathname = s.replace(/[?#].*$/, "");
+    }
+    const m = pathname.match(/\/workitems?\/([^/?#]+)/i) || pathname.match(/\/work_items\/([^/?#]+)/i);
+    if (m) {
+        const ref = { workItemRef: decode(m[1]) };
+        if (host)
+            ref.host = host;
+        return ref;
+    }
+    if (!host && /^[A-Za-z0-9_-]+$/.test(s))
+        return { workItemRef: s };
+    throw new PingCodeError(`无法从输入中解析工作项: ${input}`);
+}
+export async function getProject(client, ref) {
+    const projectRef = typeof ref === "string" ? parseProjectRef(ref) : ref;
+    let project;
+    if (projectRef.projectId) {
+        project = await client.get(`/v1/project/projects/${projectRef.projectId}`);
+    }
+    else if (projectRef.projectIdentifier) {
+        const res = await client.get("/v1/project/projects", { identifier: projectRef.projectIdentifier });
+        const values = res?.values ?? (Array.isArray(res) ? res : []);
+        if (!values.length) {
+            throw new PingCodeError(`profile "${client.profile.name}" 下找不到标识为 "${projectRef.projectIdentifier}" 的项目`);
+        }
+        project = values.length === 1 ? values[0] : values.find((p) => p.identifier === projectRef.projectIdentifier) ?? values[0];
+    }
+    else {
+        throw new PingCodeError("请提供项目 identifier 或 id");
+    }
+    if (!project?.id)
+        throw new PingCodeError("项目响应中没有 id 字段");
+    return {
+        id: project.id,
+        name: project.name,
+        identifier: project.identifier,
+        type: project.type,
+        html_url: project.html_url,
+        visibility: project.visibility,
+        description: project.description || undefined,
+    };
+}
+export async function getWorkItem(client, ref) {
+    const workRef = typeof ref === "string" ? parseWorkItemRef(ref) : ref;
+    const key = workRef.workItemRef;
+    let item;
+    // DEMO-77 style identifiers are looked up via the list filter; short/long ids go on the path.
+    if (/^[A-Za-z][A-Za-z0-9_]*-\d+$/.test(key)) {
+        const res = await client.get("/v1/project/work_items", { identifier: key });
+        const values = res?.values ?? [];
+        if (!values.length) {
+            throw new PingCodeError(`profile "${client.profile.name}" 下找不到工作项 ${key}`);
+        }
+        item = values.find((w) => w.identifier === key) ?? values[0];
+    }
+    else {
+        item = await client.get(`/v1/project/work_items/${encodeURIComponent(key)}`);
+    }
+    if (!item?.id)
+        throw new PingCodeError(`工作项 ${key} 的响应中没有 id 字段`);
+    return summarizeWorkItem(item);
+}
+export async function listSprints(client, projectId) {
+    const pageSize = 100;
+    const sprints = [];
+    for (let pageIndex = 0; pageIndex < 50; pageIndex++) {
+        const res = await client.get(`/v1/project/projects/${projectId}/sprints`, {
+            page_index: pageIndex,
+            page_size: pageSize,
+        });
+        const values = res?.values ?? [];
+        for (const s of values) {
+            sprints.push({
+                id: s.id,
+                name: s.name,
+                status: s.status,
+                start_at: s.start_at ?? null,
+                end_at: s.end_at ?? null,
+            });
+        }
+        const total = typeof res?.total === "number" ? res.total : undefined;
+        if (values.length < pageSize || (total !== undefined && sprints.length >= total))
+            break;
+    }
+    return sprints;
+}
+function findSprint(sprints, ref) {
+    if (LONG_ID_RE.test(ref))
+        return sprints.find((s) => s.id === ref);
+    const exact = sprints.filter((s) => s.name === ref);
+    if (exact.length === 1)
+        return exact[0];
+    const lower = ref.toLowerCase();
+    const ci = sprints.filter((s) => s.name?.toLowerCase() === lower);
+    return ci.length === 1 ? ci[0] : undefined;
+}
+/**
+ * Resolve a sprint for a project.
+ * - Explicit long id or name → match uniquely, else return candidates.
+ * - Board / sprint URL web short id cannot be mapped via the Open API (list has no short_id):
+ *   if exactly one sprint is in_progress, use it; otherwise return candidates (do not guess among pending).
+ * - No sprint ref: same in_progress heuristic.
+ */
+export function resolveSprintSelection(sprints, sprintRef) {
+    if (sprintRef?.trim()) {
+        const ref = sprintRef.trim();
+        const found = findSprint(sprints, ref);
+        if (found)
+            return { ok: true, sprint: found };
+        // Unmappable web short id (or unknown name): prefer the single in-progress sprint.
+        const inProgress = sprints.filter((s) => s.status === "in_progress");
+        if (inProgress.length === 1) {
+            return {
+                ok: true,
+                sprint: inProgress[0],
+                note: `无法将迭代路径段 "${ref}" 映射到 API 迭代（Open API 列表不含 web short_id）；` +
+                    `项目中恰好有一个进行中的迭代 "${inProgress[0].name}"，已选用它。若不对请显式传 sprint 名称或长 id。`,
+            };
+        }
+        return {
+            ok: false,
+            needs_sprint_selection: true,
+            candidates: sprints,
+            message: `无法将迭代路径段 "${ref}" 映射到 API 迭代（Open API 的 sprint 对象无 short_id），` +
+                `且进行中的迭代数量为 ${inProgress.length}，无法自动选定。请从 candidates 中选择（传 sprint 名称或长 id）。`,
+        };
+    }
+    const inProgress = sprints.filter((s) => s.status === "in_progress");
+    if (inProgress.length === 1)
+        return { ok: true, sprint: inProgress[0] };
+    return {
+        ok: false,
+        needs_sprint_selection: true,
+        candidates: sprints,
+        message: inProgress.length === 0
+            ? "未指定迭代，且当前没有进行中的迭代。请从 candidates 中选择。"
+            : `未指定迭代，且有 ${inProgress.length} 个进行中的迭代，无法自动选定。请从 candidates 中选择。`,
+    };
+}
+export async function listSprintWorkItems(client, projectId, sprintId, opts = {}) {
+    const incompleteOnly = !!opts.incompleteOnly;
+    // When filtering incomplete, page through so the filter is complete.
+    const fetchAll = opts.fetchAll ?? incompleteOnly;
+    if (!fetchAll) {
+        const res = await client.get("/v1/project/work_items", {
+            project_id: projectId,
+            sprint_id: sprintId,
+            page_index: opts.pageIndex,
+            page_size: opts.pageSize,
+        });
+        let values = res?.values ?? [];
+        if (incompleteOnly)
+            values = values.filter(isIncompleteWorkItem);
+        return {
+            page_index: res.page_index,
+            page_size: res.page_size,
+            total: incompleteOnly ? values.length : res.total,
+            work_items: values.map(summarizeWorkItem),
+        };
+    }
+    const pageSize = 100;
+    const all = [];
+    for (let pageIndex = 0; pageIndex < 50; pageIndex++) {
+        const res = await client.get("/v1/project/work_items", {
+            project_id: projectId,
+            sprint_id: sprintId,
+            page_index: pageIndex,
+            page_size: pageSize,
+        });
+        const values = res?.values ?? [];
+        all.push(...values);
+        const total = typeof res?.total === "number" ? res.total : undefined;
+        if (values.length < pageSize || (total !== undefined && all.length >= total))
+            break;
+    }
+    const filtered = incompleteOnly ? all.filter(isIncompleteWorkItem) : all;
+    return { total: filtered.length, work_items: filtered.map(summarizeWorkItem) };
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/comments.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { getClientFor } from "../client/profile.js";
+import { createWorkItemComment, deleteWorkItemComment, listWorkItemComments } from "../comments/index.js";
+import { parseWorkItemRef } from "../pjm/index.js";
+import { profileArg, run } from "./common.js";
+const workItemArg = {
+    work_item: z
+        .string()
+        .min(1)
+        .describe("工作项 identifier（如 DEMO-29）、短/长 id，或完整工作项 URL"),
+};
+const COMMENT_NOTE = "Open API 不支持修改评论（只有查看/新增/删除），需要改内容时只能删了重写。" +
+    "profile 选择规则与 pingcode_work_item_get 一致：完整 URL 按主机名自动选；仅有 DEMO-29 这类编号且多 profile 时先 list_profiles 再问用户。";
+export function registerCommentTools(server) {
+    server.registerTool("pingcode_work_item_comment_list", {
+        description: "列出工作项的评论。默认过滤已删除评论（is_deleted=1、内容为空）；include_deleted=true 时全部返回并标记 deleted: true。" +
+            COMMENT_NOTE,
+        inputSchema: {
+            ...workItemArg,
+            include_deleted: z.boolean().optional().describe("为 true 时包含已删除评论；默认 false"),
+            page_index: z.number().int().min(0).optional().describe("页码（仅 include_deleted=true 时生效；默认拉全量）"),
+            page_size: z.number().int().min(1).max(100).optional().describe("每页数量（同上）"),
+            ...profileArg,
+        },
+    }, ({ work_item, include_deleted, page_index, page_size, profile }) => run(async () => {
+        const ref = parseWorkItemRef(work_item);
+        const client = getClientFor({ profile, host: ref.host });
+        const res = await listWorkItemComments(client, ref, {
+            includeDeleted: include_deleted,
+            pageIndex: page_index,
+            pageSize: page_size,
+        });
+        return { profile: client.profile.name, include_deleted: !!include_deleted, ...res };
+    }));
+    server.registerTool("pingcode_work_item_comment_create", {
+        description: "给工作项新增一条评论（POST /v1/project/work_items/{id}/comments）。" + COMMENT_NOTE,
+        inputSchema: {
+            ...workItemArg,
+            content: z.string().min(1).describe("评论内容"),
+            ...profileArg,
+        },
+    }, ({ work_item, content, profile }) => run(async () => {
+        const ref = parseWorkItemRef(work_item);
+        const client = getClientFor({ profile, host: ref.host });
+        const res = await createWorkItemComment(client, ref, content);
+        return { profile: client.profile.name, ...res };
+    }));
+    server.registerTool("pingcode_work_item_comment_delete", {
+        description: "删除工作项的一条评论（DELETE /v1/comments/{id}）。删除后评论 is_deleted=1、内容清空，默认列表中不再显示。" +
+            "comment_id 可从 pingcode_work_item_comment_list 获取。" +
+            COMMENT_NOTE,
+        inputSchema: {
+            ...workItemArg,
+            comment_id: z.string().min(1).describe("评论 id（24 位十六进制）"),
+            ...profileArg,
+        },
+    }, ({ work_item, comment_id, profile }) => run(async () => {
+        const ref = parseWorkItemRef(work_item);
+        const client = getClientFor({ profile, host: ref.host });
+        const res = await deleteWorkItemComment(client, ref, comment_id);
+        return { profile: client.profile.name, deleted: true, ...res };
+    }));
+}
+//# sourceMappingURL=comments.js.map

package/dist/tools/common.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export async function run(fn) {
+    try {
+        const result = await fn();
+        const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: err.message }], isError: true };
+    }
+}
+export const profileArg = {
+    profile: z
+        .string()
+        .optional()
+        .describe("profile 名称（= PingCode 租户）。有完整 *.pingcode.com URL 时一般可省略（按主机名匹配 webBaseUrl）；" +
+        "只有 DEMO-77 / 短 id 且配置了多个 profile 时，先 pingcode_list_profiles 再询问用户选哪个，不要把「问 space/project」和「问 profile」混为一谈。"),
+};
+export const paging = {
+    page_index: z.number().int().min(0).optional().describe("页码，从 0 开始"),
+    page_size: z.number().int().min(1).max(100).optional().describe("每页数量，默认 30，最大 100"),
+};
+//# sourceMappingURL=common.js.map

package/dist/tools/pjm.js

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import { getClientFor } from "../client/profile.js";
+import { getProject, getWorkItem, listSprintWorkItems, listSprints, parseProjectRef, parseWorkItemRef, resolveSprintSelection, } from "../pjm/index.js";
+import { profileArg, run } from "./common.js";
+/** pingcode_project_get, pingcode_work_item_get. */
+export function registerProjectTools(server) {
+    server.registerTool("pingcode_project_get", {
+        description: "获取 PingCode 项目详情。支持项目 identifier（如 DEMO）、24 位 id，或完整 PJM URL（如 https://x.pingcode.com/pjm/projects/DEMO/...）。" +
+            "完整 URL 按主机名自动匹配 profile；只有短标识且多 profile 时先 pingcode_list_profiles 再询问用户选哪个租户（不要问成 wiki space）。",
+        inputSchema: {
+            project: z
+                .string()
+                .min(1)
+                .describe("项目 identifier / id，或含 /pjm/projects/... 的完整 URL"),
+            ...profileArg,
+        },
+    }, ({ project, profile }) => run(async () => {
+        const ref = parseProjectRef(project);
+        const client = getClientFor({ profile, host: ref.host });
+        const p = await getProject(client, ref);
+        return { profile: client.profile.name, project: p };
+    }));
+    server.registerTool("pingcode_work_item_get", {
+        description: "获取工作项（需求/任务等）详情。支持 identifier（DEMO-77）、短 id、24 位长 id，或工作项 URL（…/pjm/workitems/…）。" +
+            "完整 URL 按主机名自动选 profile；仅有 DEMO-77 这类编号且多 profile 时，先 list_profiles，把名称+webBaseUrl 列给用户选，不要默默用 default。",
+        inputSchema: {
+            work_item: z
+                .string()
+                .min(1)
+                .describe("工作项 identifier（如 DEMO-77）、短/长 id，或完整工作项 URL"),
+            ...profileArg,
+        },
+    }, ({ work_item, profile }) => run(async () => {
+        const ref = parseWorkItemRef(work_item);
+        const client = getClientFor({ profile, host: ref.host });
+        const item = await getWorkItem(client, ref);
+        return { profile: client.profile.name, work_item: item };
+    }));
+}
+/** pingcode_sprint_list, pingcode_sprint_work_items. */
+export function registerSprintTools(server) {
+    server.registerTool("pingcode_sprint_list", {
+        description: "列出项目下的迭代（sprint）。project 支持 identifier（DEMO）、id 或 PJM 项目/看板 URL。" +
+            "完整 URL 自动匹配 profile；多 profile 且无 URL 时先问租户再问项目。",
+        inputSchema: {
+            project: z.string().min(1).describe("项目 identifier / id，或 PJM 项目/看板 URL"),
+            ...profileArg,
+        },
+    }, ({ project, profile }) => run(async () => {
+        const ref = parseProjectRef(project);
+        const client = getClientFor({ profile, host: ref.host });
+        const p = await getProject(client, ref);
+        const sprints = await listSprints(client, p.id);
+        return { profile: client.profile.name, project: p, sprints };
+    }));
+    server.registerTool("pingcode_sprint_work_items", {
+        description: "列出某迭代下的工作项。可传 project + sprint（长 id 或名称如 Sprint2），或完整看板/迭代 URL（…/pjm/projects/DEMO/sprints/…/board）。" +
+            "incomplete_only=true 时只返回 state.type 不是 completed 的项。" +
+            "看板 URL 里的 web short id 无法从 Open API 反查：若恰好一个 in_progress 迭代则选用，否则返回 candidates 让用户选，不要猜。" +
+            "完整 URL 自动匹配 profile；多 profile 无 URL 时先问租户。",
+        inputSchema: {
+            project: z
+                .string()
+                .optional()
+                .describe("项目 identifier / id；若 url 已含 /pjm/projects/... 可省略"),
+            sprint: z
+                .string()
+                .optional()
+                .describe("迭代长 id 或名称（如 Sprint2）；看板 URL 的 short 段通常无法映射"),
+            url: z
+                .string()
+                .optional()
+                .describe("完整看板/迭代/项目 URL（可替代 project，并带出 host 与可选 sprint 路径段）"),
+            incomplete_only: z
+                .boolean()
+                .optional()
+                .describe("为 true 时只返回未完成工作项（state.type !== completed）；默认 false"),
+            page_index: z.number().int().min(0).optional().describe("页码（incomplete_only 时会拉全量再过滤，忽略分页）"),
+            page_size: z.number().int().min(1).max(100).optional().describe("每页数量（同上）"),
+            ...profileArg,
+        },
+    }, ({ project, sprint, url, incomplete_only, page_index, page_size, profile }) => run(async () => {
+        const raw = (url?.trim() || project?.trim() || "");
+        if (!raw)
+            throw new Error("请提供 project 或 url（看板/项目 URL）");
+        const ref = parseProjectRef(raw);
+        const client = getClientFor({ profile, host: ref.host });
+        const p = await getProject(client, ref);
+        const sprints = await listSprints(client, p.id);
+        const sprintInput = sprint?.trim() || ref.sprintRef;
+        const resolved = resolveSprintSelection(sprints, sprintInput);
+        if (!resolved.ok) {
+            return {
+                profile: client.profile.name,
+                project: p,
+                needs_sprint_selection: true,
+                message: resolved.message,
+                candidates: resolved.candidates,
+            };
+        }
+        const listed = await listSprintWorkItems(client, p.id, resolved.sprint.id, {
+            incompleteOnly: incomplete_only,
+            pageIndex: page_index,
+            pageSize: page_size,
+        });
+        return {
+            profile: client.profile.name,
+            project: p,
+            sprint: resolved.sprint,
+            note: resolved.note,
+            incomplete_only: !!incomplete_only,
+            ...listed,
+        };
+    }));
+}
+//# sourceMappingURL=pjm.js.map

package/dist/tools/profiles.js

@@ -0,0 +1,43 @@
+import { checkAuth } from "../client/client.js";
+import { getClientForProfile } from "../client/profile.js";
+import { configFilePath, getProfiles, maskToken } from "../config/index.js";
+import { profileArg, run } from "./common.js";
+export function registerProfileTools(server) {
+    server.registerTool("pingcode_list_profiles", {
+        description: "列出已配置的 PingCode profile（租户），包括默认 profile、apiBaseUrl、webBaseUrl、defaultSpaceIdentifier。令牌已脱敏。",
+        inputSchema: {},
+    }, () => run(async () => {
+        const set = getProfiles();
+        return {
+            default_profile: set.defaultProfile ?? null,
+            sources: set.sources,
+            config_file: configFilePath().path,
+            warnings: set.warnings.length ? set.warnings : undefined,
+            profiles: set.profiles.map((p) => ({
+                name: p.name,
+                default: p.name === set.defaultProfile,
+                apiBaseUrl: p.apiBaseUrl,
+                webBaseUrl: p.webBaseUrl ?? null,
+                defaultSpaceIdentifier: p.defaultSpaceIdentifier ?? null,
+                accessToken: maskToken(p.accessToken),
+            })),
+        };
+    }));
+    server.registerTool("pingcode_check_auth", {
+        description: "检查 PingCode 访问令牌是否有效，返回当前用户信息 (GET /v1/myself)。",
+        inputSchema: profileArg,
+    }, ({ profile }) => run(async () => {
+        const client = getClientForProfile(profile);
+        const me = await checkAuth(client);
+        return {
+            ok: true,
+            profile: client.profile.name,
+            apiBaseUrl: client.profile.apiBaseUrl,
+            id: me.id,
+            name: me.name,
+            display_name: me.display_name,
+            status: me.status,
+        };
+    }));
+}
+//# sourceMappingURL=profiles.js.map

package/dist/tools/register.js

@@ -0,0 +1,13 @@
+import { registerCommentTools } from "./comments.js";
+import { registerProjectTools, registerSprintTools } from "./pjm.js";
+import { registerProfileTools } from "./profiles.js";
+import { registerWikiTools } from "./wiki.js";
+/** Register every tool; order matches the tool list clients see. */
+export function registerAllTools(server) {
+    registerProfileTools(server);
+    registerWikiTools(server);
+    registerProjectTools(server);
+    registerCommentTools(server);
+    registerSprintTools(server);
+}
+//# sourceMappingURL=register.js.map

package/dist/tools/wiki.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { getClientFor, getClientForProfile } from "../client/profile.js";
+import { listPages, listSpaces, parsePageRef, readWikiPage, resolveSpaceId } from "../wiki/index.js";
+import { paging, profileArg, run } from "./common.js";
+export function registerWikiTools(server) {
+    server.registerTool("pingcode_wiki_read_page", {
+        description: "读取 PingCode 知识库页面的 Markdown 内容。支持完整页面 URL（如 https://x.pingcode.com/wiki/spaces/DEMO/pages/ZVRJX7WI 或 /wiki/pages/ID）、短 ID（如 ZVRJX7WI）或 24 位十六进制长 ID。" +
+            "完整 URL 按主机名自动匹配 profile 的 webBaseUrl，不要再问用户选租户；仅短 id 且多 profile 时先 list_profiles 再问。wiki space（如 DEMO）与 profile（租户）是不同概念。",
+        inputSchema: {
+            url_or_id: z.string().min(1).describe("页面 URL、短 ID 或 24 位长 ID"),
+            ...profileArg,
+        },
+    }, ({ url_or_id, profile }) => run(async () => {
+        const ref = parsePageRef(url_or_id);
+        const client = getClientFor({ profile, host: ref.host });
+        const page = await readWikiPage(client, ref);
+        const spaceIds = page.space ? [page.space.identifier, page.space.id].filter(Boolean).join(", ") : "";
+        const meta = [
+            `# ${page.title ?? "(无标题)"}`,
+            "",
+            `- profile: ${client.profile.name}`,
+            `- id: ${page.id}`,
+            page.short_id ? `- short_id: ${page.short_id}` : undefined,
+            page.space ? `- space: ${[page.space.name, spaceIds && `(${spaceIds})`].filter(Boolean).join(" ")}` : undefined,
+            page.html_url ? `- url: ${page.html_url}` : undefined,
+            "",
+            "---",
+            "",
+        ].filter((l) => l !== undefined);
+        return meta.join("\n") + page.markdown;
+    }));
+    server.registerTool("pingcode_wiki_list_spaces", {
+        description: "列出 PingCode 知识库空间 (GET /v1/wiki/spaces)。",
+        inputSchema: { ...paging, ...profileArg },
+    }, ({ page_index, page_size, profile }) => run(async () => {
+        const client = getClientForProfile(profile);
+        const res = await listSpaces(client, page_index, page_size);
+        return {
+            profile: client.profile.name,
+            page_index: res.page_index,
+            page_size: res.page_size,
+            total: res.total,
+            spaces: (res.values ?? []).map((s) => ({
+                id: s.id,
+                name: s.name,
+                identifier: s.identifier,
+                visibility: s.visibility,
+                description: s.description,
+            })),
+        };
+    }));
+    server.registerTool("pingcode_wiki_list_pages", {
+        description: "列出指定知识库空间下的页面 (GET /v1/wiki/pages?space_id=...)。空间可用 space_id（24 位）或 space_identifier / space（如 DEMO）指定；" +
+            "都省略时使用 profile 的 defaultSpaceIdentifier。",
+        inputSchema: {
+            space_id: z.string().optional().describe("空间 ID（24 位，可通过 pingcode_wiki_list_spaces 获取）"),
+            space_identifier: z.string().optional().describe("空间标识，如 DEMO（自动解析为 space_id）"),
+            space: z.string().optional().describe("空间 ID 或空间标识（space_id / space_identifier 的简写）"),
+            ...paging,
+            ...profileArg,
+        },
+    }, ({ space_id, space_identifier, space, page_index, page_size, profile }) => run(async () => {
+        const client = getClientForProfile(profile);
+        const spaceRef = space_id?.trim() || space_identifier?.trim() || space?.trim() || client.profile.defaultSpaceIdentifier;
+        if (!spaceRef) {
+            throw new Error(`请提供 space_id、space_identifier 或 space（profile "${client.profile.name}" 未配置 defaultSpaceIdentifier）。`);
+        }
+        const spaceId = await resolveSpaceId(client, spaceRef);
+        const res = await listPages(client, spaceId, page_index, page_size);
+        return {
+            profile: client.profile.name,
+            space_id: spaceId,
+            space_ref: spaceRef !== spaceId ? spaceRef : undefined,
+            page_index: res.page_index,
+            page_size: res.page_size,
+            total: res.total,
+            pages: (res.values ?? []).map((p) => ({
+                id: p.id,
+                short_id: p.short_id,
+                name: p.name,
+                type: p.type,
+                parent_id: p.parent?.id ?? null,
+                html_url: p.html_url,
+            })),
+        };
+    }));
+}
+//# sourceMappingURL=wiki.js.map