@tomingtoming/kioq 0.7.0

package/dist/src/index.js

@@ -0,0 +1,1305 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { lintStructureResponseModeHint, lintStructureResponsePlan, summarizeLintStructureResponse, } from "./auditResponseSummary.js";
+import { loadConfig } from "./config.js";
+import { memoryContractResponseModeHint, memoryContractResponsePlan, summarizeMemoryContractResponse, } from "./contractResponseSummary.js";
+import { summarizeNoConflict } from "./conflictSummary.js";
+import { LocalNoteStore } from "./noteStore.js";
+import { GitHubStorage, LocalFsStorage } from "./storage/index.js";
+import { normalizeDateInput, preview } from "./normalizers.js";
+import { summarizeDeleteImpact, summarizeRenameImpact } from "./operationImpact.js";
+import { summarizeBacklinksResponse, summarizeContextBundleResponse, summarizeReadNoteResponse, summarizeRecentResponse, summarizeResolveLinksResponse, summarizeSearchResponse, } from "./readResponseSummary.js";
+import { summarizeLintChangeTrigger, summarizeReadChangeTrigger } from "./changeTriggerSummary.js";
+import { RESPONSE_MODE_VALUES, normalizeResponseMode, responseModeAtLeast } from "./responseMode.js";
+import { TOOL_SCOPE_LABELS, responsibilityWarningCode } from "./toolScope.js";
+import { summarizeAppendResponse, summarizeDeleteResponse, summarizePromoteResponse, summarizeRenameResponse, summarizeWriteFlowResponse, summarizeWriteNoteResponse, } from "./writeResponseSummary.js";
+function textResult(text) {
+    return {
+        content: [{ type: "text", text }],
+    };
+}
+function normalizeError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function insertBeforeLine(lines, prefix, line) {
+    const index = lines.findIndex((item) => item.startsWith(prefix));
+    if (index >= 0) {
+        lines.splice(index, 0, line);
+        return;
+    }
+    lines.push(line);
+}
+function appendUnresolvedWikiLinks(lines, unresolved) {
+    if (unresolved.length === 0) {
+        return;
+    }
+    lines.push("");
+    lines.push("未解決 WikiLink:");
+    unresolved.forEach((target, index) => {
+        lines.push(`${index + 1}. ${target}`);
+    });
+}
+function appendUnresolvedLinkHints(lines, hints) {
+    if (hints.length === 0) {
+        return;
+    }
+    lines.push("");
+    lines.push("未解決 WikiLink 候補:");
+    hints.forEach((hint, index) => {
+        lines.push(`${index + 1}. target: ${hint.target}`);
+        if (hint.suggestions.length === 0) {
+            lines.push("   suggestion: (none)");
+            return;
+        }
+        hint.suggestions.forEach((suggestion) => {
+            const reasons = suggestion.reasons.length > 0 ? suggestion.reasons.join(",") : "-";
+            lines.push(`   suggestion: ${suggestion.title} (${suggestion.filePath}) score=${suggestion.score} reasons=${reasons}`);
+        });
+    });
+}
+function appendDuplicateWarnings(lines, warnings) {
+    if (warnings.length === 0) {
+        return;
+    }
+    lines.push("");
+    lines.push("重複警告:");
+    warnings.forEach((warning, index) => {
+        lines.push(`${index + 1}. kind: ${warning.kind}`);
+        lines.push(`   value: ${warning.value}`);
+        lines.push(`   count: ${warning.count}`);
+        warning.examples.forEach((example) => {
+            lines.push(`   example: ${example}`);
+        });
+    });
+}
+function appendStructureScore(lines, structureScore) {
+    lines.push(`structure_score: ${structureScore.score} (${structureScore.grade})`);
+    if (structureScore.nextActions.length === 0) {
+        lines.push("structure_next_actions: (none)");
+        return;
+    }
+    lines.push("structure_next_actions:");
+    structureScore.nextActions.forEach((action, index) => {
+        lines.push(`${index + 1}. ${action}`);
+    });
+}
+function appendMemoryContract(lines, contract) {
+    lines.push(`memory_contract: ${contract.status} (v${contract.version})`);
+    lines.push(`memory_contract_signals: resolved=${contract.signals.resolvedLinks} unresolved=${contract.signals.unresolvedLinks} backlinks=${contract.signals.backlinks} parent=${contract.signals.parentLinks} related=${contract.signals.relatedLinks} tags=${contract.signals.tags}`);
+    if (contract.violations.length === 0) {
+        lines.push("memory_contract_violations: (none)");
+        return;
+    }
+    lines.push("memory_contract_violations:");
+    contract.violations.forEach((violation, index) => {
+        lines.push(`${index + 1}. ${violation.code}`);
+        lines.push(`   message: ${violation.message}`);
+        lines.push(`   suggestion: ${violation.suggestion}`);
+    });
+}
+function appendBoundaryWarnings(lines, warnings) {
+    if (warnings.length === 0) {
+        return;
+    }
+    lines.push("");
+    lines.push("boundary_warnings:");
+    warnings.forEach((warning, index) => {
+        lines.push(`${index + 1}. ${warning.code}`);
+        lines.push(`   message: ${warning.message}`);
+        lines.push(`   suggestion: ${warning.suggestion}`);
+    });
+}
+function appendScopeLabel(lines, scopeLabel) {
+    lines.push(`scope_label: ${scopeLabel}`);
+}
+function appendResponsibilityWarning(lines, warnings) {
+    lines.push(`responsibility_warning: ${responsibilityWarningCode(warnings)}`);
+}
+function appendTemplateHints(lines, hints) {
+    lines.push(`template_hint_primary: ${hints.primary}`);
+    lines.push(`template_hint_doc: docs/note-templates.md`);
+    if (hints.alternatives && hints.alternatives.length > 0) {
+        lines.push(`template_hint_alternatives: ${hints.alternatives.join(", ")}`);
+    }
+    lines.push(`template_hint_reason: ${hints.reason}`);
+    if (hints.whenToSwitch) {
+        lines.push(`template_hint_when_to_switch: ${hints.whenToSwitch}`);
+    }
+}
+function appendIndexNoteCandidates(lines, candidates, heading = "index_note_candidates") {
+    lines.push(`${heading}: ${candidates.length}`);
+    if (candidates.length === 0) {
+        return;
+    }
+    candidates.forEach((item, index) => {
+        lines.push(`${index + 1}. ${item.title}`);
+        lines.push(`   permalink: ${item.permalink}`);
+        lines.push(`   file: ${item.filePath}`);
+        lines.push(`   score: ${item.score}`);
+        lines.push(`   reasons: ${item.reasons.join(", ")}`);
+    });
+}
+function appendExplorationGuidance(lines, guidance) {
+    const hasDirectoryScopeHint = Boolean(guidance.directoryScopeHint);
+    const hasQueryPresets = guidance.queryPresets.length > 0;
+    if (!hasDirectoryScopeHint && !hasQueryPresets) {
+        return;
+    }
+    lines.push("");
+    lines.push("exploration_guidance:");
+    if (guidance.directoryScopeHint) {
+        lines.push("directory_scope_hint:");
+        lines.push(`  tool: ${guidance.directoryScopeHint.suggestedTool}`);
+        lines.push(`  directory: ${guidance.directoryScopeHint.directory}`);
+        lines.push(`  reason: ${guidance.directoryScopeHint.reason}`);
+    }
+    else {
+        lines.push("directory_scope_hint: (none)");
+    }
+    lines.push(`query_presets: ${guidance.queryPresets.length}`);
+    guidance.queryPresets.forEach((preset, index) => {
+        lines.push(`${index + 1}. ${preset.query}`);
+        lines.push(`   reason: ${preset.reason}`);
+    });
+}
+function appendIndexLike(lines, indexLike, reasons, prefix = "") {
+    const key = prefix.length > 0 ? `${prefix}_index_like` : "index_like";
+    const reasonsKey = prefix.length > 0 ? `${prefix}_index_like_reasons` : "index_like_reasons";
+    lines.push(`${key}: ${indexLike ? "yes" : "no"}`);
+    lines.push(`${reasonsKey}: ${indexLike && reasons.length > 0 ? reasons.join(", ") : "(none)"}`);
+}
+function appendDocumentClarity(lines, clarity, verbose) {
+    lines.push(`document_clarity: ${clarity.status}`);
+    lines.push(`title_presence: ${clarity.titlePresence ? "yes" : "no"}`);
+    lines.push(`summary_presence: ${clarity.summaryPresence ? "yes" : "no"}`);
+    lines.push(`list_ratio: ${clarity.listRatio}`);
+    lines.push(`long_sentence_count: ${clarity.longSentenceCount}`);
+    if (verbose) {
+        lines.push(`clarity_attention_reasons: ${clarity.attentionReasons.length > 0 ? clarity.attentionReasons.join(", ") : "(none)"}`);
+    }
+}
+function appendProjectHealthSummary(lines, health) {
+    const auditSummary = summarizeLintStructureResponse({
+        unresolvedWikiLinkCount: health.unresolvedWikiLinkCount,
+        memoryContractViolationCount: health.memoryContractViolationCount,
+        duplicateWarningCount: health.duplicateWarningCount,
+        dependencyDirectionViolationCount: health.technicalDebtSignals.dependencyDirectionViolationCount,
+        weakStructureCount: health.weakStructureCount,
+        orphanNoteCount: health.orphanNoteCount,
+        staleFlowCount: health.technicalDebtSignals.staleFlowCount,
+        singleUseTagCandidateCount: health.technicalDebtSignals.singleUseTagCandidateCount,
+        titleBodyMismatchCandidateCount: health.technicalDebtSignals.titleBodyMismatchCandidateCount,
+        firstIssueTitle: health.issues[0]?.noteTitle,
+    });
+    const hasAttention = health.unresolvedWikiLinkCount > 0
+        || health.duplicateWarningCount > 0
+        || health.technicalDebtSignals.dependencyDirectionViolationCount > 0
+        || health.memoryContractViolationCount > 0
+        || health.weakStructureCount > 0
+        || health.orphanNoteCount > 0;
+    lines.push("");
+    lines.push("project_health:");
+    lines.push(`- status: ${hasAttention ? "attention" : "ok"}`);
+    lines.push(`- project: ${health.project}`);
+    lines.push(`- notes: ${health.noteCount}`);
+    lines.push(`- avg_structure_score: ${health.averageScore}`);
+    lines.push(`- grades: A=${health.gradeCounts.A} B=${health.gradeCounts.B} C=${health.gradeCounts.C} D=${health.gradeCounts.D}`);
+    lines.push(`- unresolved_wikilinks: ${health.unresolvedWikiLinkCount}`);
+    lines.push(`- orphan_notes: ${health.orphanNoteCount}`);
+    lines.push(`- duplicate_warnings: ${health.duplicateWarningCount}`);
+    lines.push(`- weak_structure_notes: ${health.weakStructureCount}`);
+    lines.push(`- memory_contract_violations: ${health.memoryContractViolationCount}`);
+    lines.push(`- dependency_direction_violations: ${health.technicalDebtSignals.dependencyDirectionViolationCount}`);
+    lines.push(`- primary_quality_signal: ${auditSummary.primaryQualitySignal}`);
+    lines.push(`- next_recommended_action: ${auditSummary.nextRecommendedAction}`);
+    if (auditSummary.nextRecommendedTarget) {
+        lines.push(`- next_recommended_target: ${auditSummary.nextRecommendedTarget}`);
+    }
+    lines.push(`- stale_flow_count: ${health.technicalDebtSignals.staleFlowCount} (days>=${health.technicalDebtSignals.staleFlowDays})`);
+    lines.push(`- stale_flow_age_buckets: near_threshold=${health.technicalDebtSignals.staleFlowAgeBuckets.nearThreshold} aging=${health.technicalDebtSignals.staleFlowAgeBuckets.aging} long_stale=${health.technicalDebtSignals.staleFlowAgeBuckets.longStale}`);
+    lines.push(`- oldest_stale_flow_days: ${health.technicalDebtSignals.oldestStaleFlowDays ?? "(none)"}`);
+    lines.push(`- cleanup_ratio: ${health.technicalDebtSignals.cleanupRatio}`);
+    lines.push(`- cleanup_ready_count: ${health.technicalDebtSignals.cleanupReadyCount}`);
+    lines.push(`- attention_note_count: ${health.technicalDebtSignals.attentionNoteCount}`);
+    lines.push(`- dependency_direction_violation_count: ${health.technicalDebtSignals.dependencyDirectionViolationCount}`);
+    lines.push(`- single_use_tag_candidate_count: ${health.technicalDebtSignals.singleUseTagCandidateCount}`);
+    lines.push(`- title_body_mismatch_candidate_count: ${health.technicalDebtSignals.titleBodyMismatchCandidateCount}`);
+    lines.push(`- unresolved_wikilinks_delta: unavailable (${health.technicalDebtSignals.unresolvedWikilinksDeltaStatus})`);
+    if (health.issues.length === 0) {
+        lines.push("- top_issues: (none)");
+        return;
+    }
+    lines.push("- top_issues:");
+    health.issues.forEach((issue, index) => {
+        lines.push(`  ${index + 1}. [${issue.severity}] ${issue.category} (${issue.notePath})`);
+        lines.push(`     suggestion: ${issue.suggestion}`);
+    });
+}
+function appendReadResponseSummary(lines, summary) {
+    lines.push(`primary_navigation_signal: ${summary.primaryNavigationSignal}`);
+    lines.push(`primary_quality_signal: ${summary.primaryQualitySignal}`);
+    lines.push(`next_recommended_action: ${summary.nextRecommendedAction}`);
+    if (summary.nextRecommendedTarget) {
+        lines.push(`next_recommended_target: ${summary.nextRecommendedTarget}`);
+    }
+}
+function appendAuditResponseSummary(lines, summary) {
+    lines.push(`primary_navigation_signal: ${summary.primaryNavigationSignal}`);
+    lines.push(`primary_quality_signal: ${summary.primaryQualitySignal}`);
+    lines.push(`next_recommended_action: ${summary.nextRecommendedAction}`);
+    if (summary.nextRecommendedTarget) {
+        lines.push(`next_recommended_target: ${summary.nextRecommendedTarget}`);
+    }
+    if (summary.recommendedResponseMode) {
+        lines.push(`recommended_response_mode: ${summary.recommendedResponseMode}`);
+    }
+    if (summary.responseModeHint) {
+        lines.push(`response_mode_hint: ${summary.responseModeHint}`);
+    }
+}
+function appendChangeTriggerSummary(lines, summary) {
+    lines.push(`change_trigger: ${summary.code}`);
+    if (summary.code === "none") {
+        return;
+    }
+    lines.push(`trigger_confidence: ${summary.confidence}`);
+    lines.push(`cascade_targets: ${summary.cascadeTargets?.join(", ") ?? "(none)"}`);
+    lines.push(`noise_risk: ${summary.noiseRisk}`);
+}
+function appendOperationImpact(lines, impact) {
+    lines.push(`impact_score: ${impact.impactScore}`);
+    lines.push(`requires_backup: ${impact.requiresBackup ? "yes" : "no"}`);
+    lines.push(`impact_reasons: ${impact.reasons.join(", ")}`);
+}
+function appendConflictSummary(lines, summary) {
+    lines.push(`conflict_type: ${summary.conflictType}`);
+    lines.push(`server_updated: ${summary.serverUpdated}`);
+    lines.push(`retry_hint: ${summary.retryHint}`);
+}
+const responseModeSchema = z.enum(RESPONSE_MODE_VALUES).optional().describe("default: standard");
+async function main() {
+    const config = loadConfig();
+    const storage = config.github
+        ? new GitHubStorage(config.github, config.root)
+        : new LocalFsStorage(config.root);
+    await storage.ensureRoot();
+    const store = new LocalNoteStore(config, storage);
+    const appendStorageContext = (lines) => {
+        lines.push(`storage_backend: ${config.github ? "github" : "filesystem"}`);
+        lines.push(`storage_root: ${config.root}`);
+        if (config.github) {
+            lines.push(`storage_repo: ${config.github.owner}/${config.github.repo}`);
+            lines.push(`storage_branch: ${config.github.branch}`);
+        }
+    };
+    const appendAutoProjectHealth = async (lines) => {
+        try {
+            const health = await store.lintStructure({
+                limit: 3,
+            });
+            appendProjectHealthSummary(lines, health);
+        }
+        catch (error) {
+            lines.push("");
+            lines.push(`project_health: unavailable (${normalizeError(error)})`);
+        }
+    };
+    const server = new McpServer({
+        name: "kioq",
+        version: "0.7.0",
+    });
+    server.tool("recent_notes", "最近更新したノートを一覧します。", {
+        limit: z.number().int().min(1).max(50).optional().describe("最大件数 (default: 10)"),
+        directory: z.string().min(1).optional().describe("指定時は配下ディレクトリに限定"),
+        response_mode: responseModeSchema,
+    }, async ({ limit, directory, response_mode }) => {
+        const responseMode = normalizeResponseMode(response_mode);
+        const result = await store.recentNotes({
+            limit: limit ?? 10,
+            directory,
+        });
+        const firstIndexLike = result.results.find((item) => item.indexLike);
+        const summary = summarizeRecentResponse({
+            resultCount: result.results.length,
+            firstResultTitle: result.results[0]?.title,
+            hasIndexLikeResult: Boolean(firstIndexLike),
+            firstIndexLikeTitle: firstIndexLike?.title,
+            indexCandidateCount: result.indexNoteCandidates.length,
+            firstIndexCandidateTitle: result.indexNoteCandidates[0]?.title,
+        });
+        const lines = [];
+        lines.push(`対象プロジェクト: ${result.project}`);
+        appendStorageContext(lines);
+        appendScopeLabel(lines, TOOL_SCOPE_LABELS.recent_notes);
+        lines.push(`response_mode: ${responseMode}`);
+        appendReadResponseSummary(lines, summary);
+        lines.push(`件数: ${result.results.length}`);
+        lines.push("");
+        if (result.results.length === 0) {
+            lines.push("候補が見つかりませんでした。");
+        }
+        else {
+            result.results.forEach((item, index) => {
+                lines.push(`${index + 1}. ${item.title}`);
+                lines.push(`   updated: ${item.updated}`);
+                if (responseModeAtLeast(responseMode, "standard")) {
+                    lines.push(`   permalink: ${item.permalink}`);
+                    lines.push(`   file: ${item.filePath}`);
+                    lines.push(`   index_like: ${item.indexLike ? "yes" : "no"}`);
+                }
+                if (responseModeAtLeast(responseMode, "verbose")) {
+                    lines.push(`   index_like_reasons: ${item.indexLike && item.indexReasons.length > 0 ? item.indexReasons.join(", ") : "(none)"}`);
+                }
+            });
+        }
+        if (responseModeAtLeast(responseMode, "verbose")) {
+            lines.push("");
+            appendIndexNoteCandidates(lines, result.indexNoteCandidates, "recommended_indexes");
+        }
+        if (responseModeAtLeast(responseMode, "verbose")) {
+            await appendAutoProjectHealth(lines);
+        }
+        return textResult(lines.join("\n"));
+    });
+    server.tool("search_notes", "ローカルの markdown ノートを検索します。", {
+        query: z.string().min(1),
+        limit: z.number().int().min(1).max(50).optional().describe("最大件数 (default: 8)"),
+        after_date: z.string().optional().describe("YYYY-MM-DD 形式。更新日で絞り込み"),
+        response_mode: responseModeSchema,
+    }, async ({ query, limit, after_date, response_mode }) => {
+        const responseMode = normalizeResponseMode(response_mode);
+        const normalizedAfterDate = normalizeDateInput(after_date);
+        if (after_date && !normalizedAfterDate) {
+            return textResult(`after_date の形式が不正です: ${after_date} (YYYY-MM-DD)`);
+        }
+        const result = await store.searchNotes({
+            query,
+            limit: limit ?? 8,
+            afterDate: normalizedAfterDate,
+        });
+        const firstIndexLike = result.results.find((item) => item.indexLike);
+        const summary = summarizeSearchResponse({
+            resultCount: result.results.length,
+            firstResultTitle: result.results[0]?.title,
+            hasIndexLikeResult: Boolean(firstIndexLike),
+            firstIndexLikeTitle: firstIndexLike?.title,
+            indexCandidateCount: result.indexNoteCandidates.length,
+            firstIndexCandidateTitle: result.indexNoteCandidates[0]?.title,
+        });
+        const lines = [];
+        lines.push(`検索クエリ: ${query}`);
+        lines.push(`対象プロジェクト: ${result.project}`);
+        appendStorageContext(lines);
+        appendScopeLabel(lines, TOOL_SCOPE_LABELS.search_notes);
+        lines.push(`response_mode: ${responseMode}`);
+        appendReadResponseSummary(lines, summary);
+        lines.push(`ヒット件数: ${result.results.length}`);
+        lines.push(`exact_identifier_matches: ${result.exactIdentifierMatchCount}`);
+        lines.push("");
+        if (result.results.length === 0) {
+            lines.push("候補が見つかりませんでした。");
+        }
+        else {
+            result.results.forEach((item, index) => {
+                lines.push(`${index + 1}. ${item.title}`);
+                lines.push(`   score: ${item.score}`);
+                lines.push(`   抜粋: ${preview(item.content, config.previewLength)}`);
+                if (responseModeAtLeast(responseMode, "standard")) {
+                    lines.push(`   permalink: ${item.permalink}`);
+                    lines.push(`   file: ${item.filePath}`);
+                    lines.push(`   exact_identifier_match: ${item.exactIdentifierMatch ? "yes" : "no"}`);
+                    lines.push(`   index_like: ${item.indexLike ? "yes" : "no"}`);
+                }
+                if (responseModeAtLeast(responseMode, "verbose")) {
+                    lines.push(`   index_like_reasons: ${item.indexLike && item.indexReasons.length > 0 ? item.indexReasons.join(", ") : "(none)"}`);
+                }
+            });
+        }
+        if (responseModeAtLeast(responseMode, "verbose")) {
+            lines.push("");
+            appendIndexNoteCandidates(lines, result.indexNoteCandidates, "recommended_indexes");
+        }
+        if (responseModeAtLeast(responseMode, "standard")) {
+            appendExplorationGuidance(lines, result.explorationGuidance);
+        }
+        return textResult(lines.join("\n"));
+    });
+    server.tool("read_note", "ノートを identifier (title / permalink / relative path) で読み取ります。", {
+        identifier: z.string().min(1),
+        response_mode: responseModeSchema,
+    }, async ({ identifier, response_mode }) => {
+        const responseMode = normalizeResponseMode(response_mode);
+        try {
+            const result = await store.readNote(identifier);
+            const summary = summarizeReadNoteResponse({
+                indexLike: result.indexLike,
+                unresolvedWikiLinkCount: result.unresolvedWikiLinks.length,
+                boundaryWarningCount: result.boundaryWarnings.length,
+                orphanWarning: result.orphanWarning,
+                backlinkCount: result.backlinkCount,
+                clarityAttention: result.documentClarity.status === "attention",
+                indexCandidateTitle: result.indexNoteCandidates[0]?.title,
+            });
+            const changeTrigger = summarizeReadChangeTrigger({
+                unresolvedWikiLinkCount: result.unresolvedWikiLinks.length,
+                boundaryWarningCount: result.boundaryWarnings.length,
+                orphanWarning: result.orphanWarning,
+                clarityAttention: result.documentClarity.status === "attention",
+                indexCandidateAvailable: result.indexNoteCandidates.length > 0,
+            });
+            const lines = [
+                `identifier: ${identifier}`,
+                `project: ${result.project}`,
+                `storage_backend: ${config.github ? "github" : "filesystem"}`,
+                `storage_root: ${config.root}`,
+                `scope_label: ${TOOL_SCOPE_LABELS.read_note}`,
+                `response_mode: ${responseMode}`,
+                `primary_navigation_signal: ${summary.primaryNavigationSignal}`,
+                `primary_quality_signal: ${summary.primaryQualitySignal}`,
+                `next_recommended_action: ${summary.nextRecommendedAction}`,
+                `file: ${result.note.relativePath}`,
+                `permalink: ${result.note.permalink}`,
+            ];
+            if (config.github) {
+                lines.splice(4, 0, `storage_repo: ${config.github.owner}/${config.github.repo}`, `storage_branch: ${config.github.branch}`);
+            }
+            if (summary.nextRecommendedTarget) {
+                insertBeforeLine(lines, "next_recommended_action:", `next_recommended_target: ${summary.nextRecommendedTarget}`);
+            }
+            appendChangeTriggerSummary(lines, changeTrigger);
+            appendResponsibilityWarning(lines, result.boundaryWarnings);
+            appendBoundaryWarnings(lines, result.boundaryWarnings);
+            if (responseModeAtLeast(responseMode, "standard")) {
+                lines.push(`link_health: ${result.linkHealth.resolved}/${result.linkHealth.total} resolved`);
+                lines.push(`backlinks: ${result.backlinkCount}`);
+                lines.push(`orphan_warning: ${result.orphanWarning ? "yes" : "no"}`);
+                appendDocumentClarity(lines, result.documentClarity, responseModeAtLeast(responseMode, "verbose"));
+                appendUnresolvedWikiLinks(lines, result.unresolvedWikiLinks);
+            }
+            if (responseModeAtLeast(responseMode, "verbose")) {
+                appendIndexLike(lines, result.indexLike, result.indexReasons);
+                appendIndexNoteCandidates(lines, result.indexNoteCandidates);
+                appendUnresolvedLinkHints(lines, result.unresolvedLinkHints);
+            }
+            lines.push("");
+            lines.push("--- note ---");
+            lines.push(result.note.raw);
+            return textResult(lines.join("\n"));
+        }
+        catch (error) {
+            let fallback;
+            try {
+                fallback = await store.suggestNotes({
+                    query: identifier,
+                    limit: 5,
+                });
+            }
+            catch {
+                fallback = undefined;
+            }
+            const lines = [];
+            lines.push(`read_note に失敗: ${normalizeError(error)}`);
+            appendStorageContext(lines);
+            appendScopeLabel(lines, TOOL_SCOPE_LABELS.read_note);
+            lines.push(`response_mode: ${responseMode}`);
+            lines.push("近い候補:");
+            if (!fallback || fallback.results.length === 0) {
+                lines.push("- 候補なし");
+            }
+            else {
+                fallback.results.forEach((item, index) => {
+                    lines.push(`${index + 1}. ${item.title}`);
+                    lines.push(`   score: ${item.score}`);
+                    lines.push(`   permalink: ${item.permalink}`);
+                    lines.push(`   file: ${item.filePath}`);
+                    lines.push(`   exact_identifier_match: ${item.exactIdentifierMatch ? "yes" : "no"}`);
+                });
+            }
+            return textResult(lines.join("\n"));
+        }
+    });
+    server.tool("resolve_links", "ノート内の WikiLink を解決し、リンク先の存在状況を返します。", {
+        identifier: z.string().min(1),
+        response_mode: responseModeSchema,
+    }, async ({ identifier, response_mode }) => {
+        const responseMode = normalizeResponseMode(response_mode);
+        const result = await store.resolveLinks({
+            identifier,
+        });
+        const unresolvedLinkCount = result.links.filter((link) => !link.resolved).length;
+        const summary = summarizeResolveLinksResponse({
+            indexLike: result.indexLike,
+            unresolvedLinkCount,
+            boundaryWarningCount: result.boundaryWarnings.length,
+            indexCandidateTitle: result.indexNoteCandidates[0]?.title,
+        });
+        const lines = [];
+        lines.push(`identifier: ${identifier}`);
+        lines.push(`project: ${result.project}`);
+        appendStorageContext(lines);
+        appendScopeLabel(lines, TOOL_SCOPE_LABELS.resolve_links);
+        lines.push(`response_mode: ${responseMode}`);
+        appendReadResponseSummary(lines, summary);
+        appendResponsibilityWarning(lines, result.boundaryWarnings);
+        lines.push(`file: ${result.note.relativePath}`);
+        lines.push(`wikilinks: ${result.links.length}`);
+        if (responseModeAtLeast(responseMode, "verbose")) {
+            appendIndexLike(lines, result.indexLike, result.indexReasons);
+        }
+        appendBoundaryWarnings(lines, result.boundaryWarnings);
+        lines.push("");
+        if (result.links.length === 0) {
+            lines.push("WikiLink は見つかりませんでした。");
+        }
+        else {
+            result.links.forEach((link, index) => {
+                lines.push(`${index + 1}. ${link.raw}`);
+                if (link.resolved) {
+                    lines.push(`   resolved: yes`);
+                    lines.push(`   to: ${link.resolvedTitle} (${link.resolvedFilePath})`);
+                }
+                else {
+                    lines.push(`   resolved: no`);
+                    lines.push(`   reason: ${link.reason ?? "unknown"}`);
+                    lines.push(`   target: ${link.target}`);
+                }
+            });
+        }
+        if (responseModeAtLeast(responseMode, "verbose")) {
+            lines.push("");
+            appendIndexNoteCandidates(lines, result.indexNoteCandidates);
+        }
+        return textResult(lines.join("\n"));
+    });
+    server.tool("list_backlinks", "指定ノートへのバックリンク一覧を返します。", {
+        identifier: z.string().min(1),
+        limit: z.number().int().min(1).max(100).optional().describe("最大件数 (default: 20)"),
+        response_mode: responseModeSchema,
+    }, async ({ identifier, limit, response_mode }) => {
+        const responseMode = normalizeResponseMode(response_mode);
+        const result = await store.listBacklinks({
+            identifier,
+            limit: limit ?? 20,
+        });
+        const summary = summarizeBacklinksResponse({
+            indexLike: result.indexLike,
+            backlinkCount: result.backlinks.length,
+            boundaryWarningCount: result.boundaryWarnings.length,
+            firstBacklinkTitle: result.backlinks[0]?.title,
+            indexCandidateTitle: result.indexNoteCandidates[0]?.title,
+        });
+        const lines = [];
+        lines.push(`target: ${result.target.title}`);
+        lines.push(`project: ${result.project}`);
+        appendStorageContext(lines);
+        appendScopeLabel(lines, TOOL_SCOPE_LABELS.list_backlinks);
+        lines.push(`response_mode: ${responseMode}`);
+        appendReadResponseSummary(lines, summary);
+        appendResponsibilityWarning(lines, result.boundaryWarnings);
+        if (responseModeAtLeast(responseMode, "verbose")) {
+            appendIndexLike(lines, result.indexLike, result.indexReasons, "target");
+        }
+        appendBoundaryWarnings(lines, result.boundaryWarnings);
+        lines.push(`backlinks: ${result.backlinks.length}`);
+        lines.push("");
+        if (result.backlinks.length === 0) {
+            lines.push("バックリンクは見つかりませんでした。");
+        }
+        else {
+            result.backlinks.forEach((item, index) => {
+                lines.push(`${index + 1}. ${item.title}`);
+                lines.push(`   count: ${item.count}`);
+                if (responseModeAtLeast(responseMode, "standard")) {
+                    lines.push(`   file: ${item.filePath}`);
+                    lines.push(`   updated: ${item.updated}`);
+                }
+                item.examples.forEach((example) => {
+                    lines.push(`   example: ${example}`);
+                });
+            });
+        }
+        if (responseModeAtLeast(responseMode, "verbose")) {
+            lines.push("");
+            appendIndexNoteCandidates(lines, result.indexNoteCandidates);
+        }
+        return textResult(lines.join("\n"));
+    });
+    server.tool("context_bundle", "指定ノートを中心に、関連ノートを優先度付きで返します。", {
+        identifier: z.string().min(1),
+        limit: z.number().int().min(1).max(30).optional().describe("最大件数 (default: 8)"),
+        response_mode: responseModeSchema,
+    }, async ({ identifier, limit, response_mode }) => {
+        const responseMode = normalizeResponseMode(response_mode);
+        const result = await store.contextBundle({
+            identifier,
+            limit: limit ?? 8,
+        });
+        const summary = summarizeContextBundleResponse({
+            sourceIndexLike: result.source.indexLike,
+            bundleItemCount: result.items.length,
+            boundaryWarningCount: result.source.boundaryWarnings.length,
+            firstBundleItemTitle: result.items[0]?.title,
+            indexCandidateTitle: result.indexNoteCandidates[0]?.title,
+        });
+        const lines = [];
+        lines.push(`source: ${result.source.title}`);
+        lines.push(`project: ${result.project}`);
+        appendStorageContext(lines);
+        appendScopeLabel(lines, TOOL_SCOPE_LABELS.context_bundle);
+        lines.push(`response_mode: ${responseMode}`);
+        appendReadResponseSummary(lines, summary);
+        appendResponsibilityWarning(lines, result.source.boundaryWarnings);
+        if (responseModeAtLeast(responseMode, "standard")) {
+            lines.push(`memory_kind: ${result.source.memoryKind}`);
+            lines.push(`file: ${result.source.filePath}`);
+        }
+        if (responseModeAtLeast(responseMode, "verbose")) {
+            appendIndexLike(lines, result.source.indexLike, result.source.indexReasons, "source");
+        }
+        appendBoundaryWarnings(lines, result.source.boundaryWarnings);
+        lines.push(`bundle_items: ${result.items.length}`);
+        lines.push("");
+        if (result.items.length === 0) {
+            lines.push("関連ノートは見つかりませんでした。");
+        }
+        else {
+            result.items.forEach((item, index) => {
+                lines.push(`${index + 1}. ${item.title}`);
+                lines.push(`   score: ${item.score}`);
+                if (responseModeAtLeast(responseMode, "standard")) {
+                    lines.push(`   memory_kind: ${item.memoryKind}`);
+                    lines.push(`   file: ${item.filePath}`);
+                }
+                if (responseModeAtLeast(responseMode, "verbose")) {
+                    lines.push(`   reasons: ${item.reasons.join(", ")}`);
+                }
+            });
+        }
+        if (responseModeAtLeast(responseMode, "verbose")) {
+            lines.push("");
+            appendIndexNoteCandidates(lines, result.indexNoteCandidates);
+        }
+        if (responseModeAtLeast(responseMode, "standard")) {
+            appendExplorationGuidance(lines, result.explorationGuidance);
+        }
+        return textResult(lines.join("\n"));
+    });
+    server.tool("memory_contract", "kioq の Memory Contract（構造化ルール）を返します。", {
+        response_mode: responseModeSchema,
+    }, async ({ response_mode }) => {
+        const responseMode = normalizeResponseMode(response_mode);
+        const plan = memoryContractResponsePlan(responseMode);
+        const summary = {
+            ...summarizeMemoryContractResponse(),
+            ...memoryContractResponseModeHint(responseMode),
+        };
+        const contract = store.getMemoryContract();
+        const lines = [];
+        appendStorageContext(lines);
+        appendScopeLabel(lines, TOOL_SCOPE_LABELS.memory_contract);
+        lines.push(`response_mode: ${responseMode}`);
+        appendAuditResponseSummary(lines, summary);
+        lines.push(`memory_contract_version: ${contract.version}`);
+        lines.push(`required_frontmatter: ${contract.requiredFrontmatter.join(", ")}`);
+        lines.push(`flow_required_frontmatter: ${contract.flowRequiredFrontmatter.join(", ")}`);
+        lines.push(`parent_markers: ${contract.parentLinkMarkers.join(", ")}`);
+        lines.push(`source_metadata_canonical_field: ${contract.optionalSourceMetadata.canonicalField}`);
+        lines.push(`source_metadata_auxiliary_fields: ${contract.optionalSourceMetadata.auxiliaryFields.join(", ")}`);
+        lines.push(`index_threshold_score_at_least: ${contract.indexNavigationPolicy.thresholds.scoreAtLeast}`);
+        lines.push(`index_threshold_index_sections_at_least: ${contract.indexNavigationPolicy.thresholds.indexSectionsAtLeast}`);
+        lines.push(`technical_debt_threshold_stale_flow_days: ${contract.technicalDebtPolicy.thresholds.staleFlowDays}`);
+        lines.push("sample_templates_available: stock, flow, index");
+        if (!plan.includePolicyRules) {
+            return textResult(lines.join("\n"));
+        }
+        lines.push("requirements:");
+        lines.push(`- min_resolved_links: ${contract.requirements.minResolvedLinks}`);
+        lines.push(`- min_backlinks: ${contract.requirements.minBacklinks}`);
+        lines.push(`- min_parent_links: ${contract.requirements.minParentLinks}`);
+        lines.push(`- min_related_links: ${contract.requirements.minRelatedLinks}`);
+        lines.push(`- max_unresolved_links: ${contract.requirements.maxUnresolvedLinks}`);
+        lines.push(`- min_tags: ${contract.requirements.minTags}`);
+        lines.push("flow_requirements:");
+        lines.push(`- min_resolved_links: ${contract.flowRequirements.minResolvedLinks}`);
+        lines.push(`- min_backlinks: ${contract.flowRequirements.minBacklinks}`);
+        lines.push(`- min_parent_links: ${contract.flowRequirements.minParentLinks}`);
+        lines.push(`- min_related_links: ${contract.flowRequirements.minRelatedLinks}`);
+        lines.push(`- max_unresolved_links: ${contract.flowRequirements.maxUnresolvedLinks}`);
+        lines.push(`- min_tags: ${contract.flowRequirements.minTags}`);
+        lines.push("optional_source_metadata:");
+        lines.push(`- canonical_field: ${contract.optionalSourceMetadata.canonicalField}`);
+        lines.push(`- auxiliary_fields: ${contract.optionalSourceMetadata.auxiliaryFields.join(", ")}`);
+        contract.optionalSourceMetadata.rules.forEach((rule) => {
+            lines.push(`- rule: ${rule}`);
+        });
+        lines.push("index_navigation_policy:");
+        lines.push(`- excluded_memory_kinds: ${contract.indexNavigationPolicy.excludedMemoryKinds.join(", ")}`);
+        lines.push(`- threshold_score_at_least: ${contract.indexNavigationPolicy.thresholds.scoreAtLeast}`);
+        lines.push(`- threshold_index_sections_at_least: ${contract.indexNavigationPolicy.thresholds.indexSectionsAtLeast}`);
+        lines.push(`- configurable_via_env: ${contract.indexNavigationPolicy.configurableVia.env.join(", ")}`);
+        lines.push(`- configurable_via_cli: ${contract.indexNavigationPolicy.configurableVia.cli.join(", ")}`);
+        if (plan.includePolicySignals) {
+            contract.indexNavigationPolicy.signals.forEach((signal) => {
+                lines.push(`- signal: ${signal.code} weight=${signal.weight} description=${signal.description}`);
+            });
+        }
+        contract.indexNavigationPolicy.rules.forEach((rule) => {
+            lines.push(`- rule: ${rule}`);
+        });
+        lines.push("technical_debt_policy:");
+        lines.push(`- signals: ${contract.technicalDebtPolicy.signals.join(", ")}`);
+        lines.push(`- stale_flow_states: ${contract.technicalDebtPolicy.staleFlowStates.join(", ")}`);
+        lines.push(`- threshold_stale_flow_days: ${contract.technicalDebtPolicy.thresholds.staleFlowDays}`);
+        lines.push(`- stale_flow_age_bucket_near_threshold: ${contract.technicalDebtPolicy.staleFlowAgeBuckets.nearThreshold}`);
+        lines.push(`- stale_flow_age_bucket_aging: ${contract.technicalDebtPolicy.staleFlowAgeBuckets.aging}`);
+        lines.push(`- stale_flow_age_bucket_long_stale: ${contract.technicalDebtPolicy.staleFlowAgeBuckets.longStale}`);
+        lines.push(`- cleanup_ratio_definition: ${contract.technicalDebtPolicy.cleanupRatioDefinition}`);
+        lines.push(`- cleanup_ready_count_definition: ${contract.technicalDebtPolicy.cleanupReadyCountDefinition}`);
+        lines.push(`- attention_note_count_definition: ${contract.technicalDebtPolicy.attentionNoteCountDefinition}`);
+        lines.push(`- dependency_direction_violation_count_definition: ${contract.technicalDebtPolicy.dependencyDirectionViolationCountDefinition}`);
+        lines.push(`- single_use_tag_candidate_count_definition: ${contract.technicalDebtPolicy.singleUseTagCandidateCountDefinition}`);
+        lines.push(`- title_body_mismatch_candidate_count_definition: ${contract.technicalDebtPolicy.titleBodyMismatchCandidateCountDefinition}`);
+        lines.push(`- unresolved_wikilinks_delta_status: ${contract.technicalDebtPolicy.unresolvedWikilinksDeltaStatus}`);
+        lines.push(`- configurable_via_env: ${contract.technicalDebtPolicy.configurableVia.env.join(", ")}`);
+        lines.push(`- configurable_via_cli: ${contract.technicalDebtPolicy.configurableVia.cli.join(", ")}`);
+        lines.push("response_mode_policy:");
+        lines.push(`- supported_read_tools: ${contract.responseModePolicy.supportedTools.read.join(", ")}`);
+        lines.push(`- supported_audit_tools: ${contract.responseModePolicy.supportedTools.audit.join(", ")}`);
+        lines.push(`- minimal: ${contract.responseModePolicy.modes.minimal}`);
+        lines.push(`- standard: ${contract.responseModePolicy.modes.standard}`);
+        lines.push(`- verbose: ${contract.responseModePolicy.modes.verbose}`);
+        contract.responseModePolicy.rules.forEach((rule) => {
+            lines.push(`- rule: ${rule}`);
+        });
+        if (plan.includeSampleTemplates) {
+            lines.push("");
+            lines.push("sample_template_stock:");
+            lines.push("```md");
+            contract.sampleTemplates.stock.forEach((line) => lines.push(line));
+            lines.push("```");
+            lines.push("");
+            lines.push("sample_template_flow:");
+            lines.push("```md");
+            contract.sampleTemplates.flow.forEach((line) => lines.push(line));
+            lines.push("```");
+            lines.push("");
+            lines.push("sample_template_index:");
+            lines.push("```md");
+            contract.sampleTemplates.index.forEach((line) => lines.push(line));
+            lines.push("```");
+        }
+        return textResult(lines.join("\n"));
+    });
+    server.tool("lint_structure", "構造化を促すために、ノート群の問題を診断して優先順位付きで返します。", {
+        limit: z.number().int().min(1).max(200).optional().describe("返却する issue 最大件数 (default: 50)"),
+        response_mode: responseModeSchema,
+    }, async ({ limit, response_mode }) => {
+        const responseMode = normalizeResponseMode(response_mode);
+        const plan = lintStructureResponsePlan(responseMode);
+        const result = await store.lintStructure({
+            limit: limit ?? 50,
+        });
+        const summaryBase = {
+            unresolvedWikiLinkCount: result.unresolvedWikiLinkCount,
+            memoryContractViolationCount: result.memoryContractViolationCount,
+            duplicateWarningCount: result.duplicateWarningCount,
+            dependencyDirectionViolationCount: result.technicalDebtSignals.dependencyDirectionViolationCount,
+            weakStructureCount: result.weakStructureCount,
+            orphanNoteCount: result.orphanNoteCount,
+            staleFlowCount: result.technicalDebtSignals.staleFlowCount,
+            singleUseTagCandidateCount: result.technicalDebtSignals.singleUseTagCandidateCount,
+            titleBodyMismatchCandidateCount: result.technicalDebtSignals.titleBodyMismatchCandidateCount,
+            firstIssueTitle: result.issues[0]?.noteTitle,
+        };
+        const summary = {
+            ...summarizeLintStructureResponse(summaryBase),
+            ...lintStructureResponseModeHint({
+                mode: responseMode,
+                unresolvedWikiLinkCount: summaryBase.unresolvedWikiLinkCount,
+                memoryContractViolationCount: summaryBase.memoryContractViolationCount,
+                duplicateWarningCount: summaryBase.duplicateWarningCount,
+                dependencyDirectionViolationCount: summaryBase.dependencyDirectionViolationCount,
+                weakStructureCount: summaryBase.weakStructureCount,
+                orphanNoteCount: summaryBase.orphanNoteCount,
+                staleFlowCount: summaryBase.staleFlowCount,
+                singleUseTagCandidateCount: summaryBase.singleUseTagCandidateCount,
+                titleBodyMismatchCandidateCount: summaryBase.titleBodyMismatchCandidateCount,
+            }),
+        };
+        const changeTrigger = summarizeLintChangeTrigger({
+            unresolvedWikiLinkCount: summaryBase.unresolvedWikiLinkCount,
+            memoryContractViolationCount: summaryBase.memoryContractViolationCount,
+            duplicateWarningCount: summaryBase.duplicateWarningCount,
+            dependencyDirectionViolationCount: summaryBase.dependencyDirectionViolationCount,
+            weakStructureCount: summaryBase.weakStructureCount,
+            orphanNoteCount: summaryBase.orphanNoteCount,
+            staleFlowCount: summaryBase.staleFlowCount,
+            singleUseTagCandidateCount: summaryBase.singleUseTagCandidateCount,
+            titleBodyMismatchCandidateCount: summaryBase.titleBodyMismatchCandidateCount,
+        });
+        const lines = [];
+        lines.push(`project: ${result.project}`);
+        appendStorageContext(lines);
+        appendScopeLabel(lines, TOOL_SCOPE_LABELS.lint_structure);
+        lines.push(`response_mode: ${responseMode}`);
+        appendAuditResponseSummary(lines, summary);
+        appendChangeTriggerSummary(lines, changeTrigger);
+        lines.push(`notes: ${result.noteCount}`);
+        lines.push(`average_structure_score: ${result.averageScore}`);
+        lines.push(`grades: A=${result.gradeCounts.A} B=${result.gradeCounts.B} C=${result.gradeCounts.C} D=${result.gradeCounts.D}`);
+        lines.push(`unresolved_wikilinks: ${result.unresolvedWikiLinkCount}`);
+        lines.push(`orphan_notes: ${result.orphanNoteCount}`);
+        lines.push(`duplicate_warnings: ${result.duplicateWarningCount}`);
+        lines.push(`dependency_direction_violations: ${result.technicalDebtSignals.dependencyDirectionViolationCount}`);
+        lines.push(`weak_structure_notes: ${result.weakStructureCount}`);
+        lines.push(`memory_contract_violations: ${result.memoryContractViolationCount}`);
+        lines.push(`stale_flow_count: ${result.technicalDebtSignals.staleFlowCount} (days>=${result.technicalDebtSignals.staleFlowDays})`);
+        if (plan.includeDebtBreakdown) {
+            lines.push(`stale_flow_age_buckets: near_threshold=${result.technicalDebtSignals.staleFlowAgeBuckets.nearThreshold} aging=${result.technicalDebtSignals.staleFlowAgeBuckets.aging} long_stale=${result.technicalDebtSignals.staleFlowAgeBuckets.longStale}`);
+            lines.push(`oldest_stale_flow_days: ${result.technicalDebtSignals.oldestStaleFlowDays ?? "(none)"}`);
+            lines.push(`cleanup_ratio: ${result.technicalDebtSignals.cleanupRatio}`);
+            lines.push(`cleanup_ready_count: ${result.technicalDebtSignals.cleanupReadyCount}`);
+            lines.push(`attention_note_count: ${result.technicalDebtSignals.attentionNoteCount}`);
+            lines.push(`dependency_direction_violation_count: ${result.technicalDebtSignals.dependencyDirectionViolationCount}`);
+            lines.push(`single_use_tag_candidate_count: ${result.technicalDebtSignals.singleUseTagCandidateCount}`);
+            lines.push(`title_body_mismatch_candidate_count: ${result.technicalDebtSignals.titleBodyMismatchCandidateCount}`);
+            lines.push(`unresolved_wikilinks_delta: unavailable (${result.technicalDebtSignals.unresolvedWikilinksDeltaStatus})`);
+        }
+        lines.push(`issues: ${result.issues.length}`);
+        if (result.issues.length === 0) {
+            lines.push("");
+            lines.push("問題は見つかりませんでした。");
+        }
+        else if (plan.includeDetailedIssues) {
+            lines.push("");
+            result.issues.forEach((issue, index) => {
+                lines.push(`${index + 1}. [${issue.severity}] ${issue.category}`);
+                lines.push(`   note: ${issue.noteTitle}`);
+                lines.push(`   file: ${issue.notePath}`);
+                lines.push(`   message: ${issue.message}`);
+                lines.push(`   suggestion: ${issue.suggestion}`);
+            });
+        }
+        else if (plan.includeCompactIssues) {
+            lines.push("");
+            lines.push("top_issues:");
+            result.issues.forEach((issue, index) => {
+                lines.push(`${index + 1}. [${issue.severity}] ${issue.category} :: ${issue.noteTitle}`);
+            });
+        }
+        if (result.orphanRepairQueue.length > 0 && responseMode !== "minimal") {
+            lines.push("");
+            lines.push("orphan_repair_queue:");
+            result.orphanRepairQueue.forEach((item, index) => {
+                if (responseMode === "verbose") {
+                    lines.push(`${index + 1}. ${item.noteTitle}`);
+                    lines.push(`   file: ${item.notePath}`);
+                    lines.push(`   category: ${item.category}`);
+                    lines.push(`   impact: ${item.impact}`);
+                    if (item.suggestedParent) {
+                        lines.push(`   suggested_parent: ${item.suggestedParent.title} (${item.suggestedParent.permalink})`);
+                        lines.push(`   reasons: ${item.suggestedParent.reasons.join(", ")}`);
+                    }
+                    return;
+                }
+                const suffix = item.suggestedParent
+                    ? ` -> ${item.suggestedParent.title}`
+                    : " -> (manual)";
+                lines.push(`${index + 1}. ${item.noteTitle} :: ${item.category}${suffix}`);
+            });
+        }
+        return textResult(lines.join("\n"));
+    });
+    server.tool("write_note", "ローカル markdown ノートを作成/更新します。", {
+        title: z.string().min(1),
+        content: z.string().min(1),
+        directory: z.string().min(1).optional().describe("default: KIOQ_DEFAULT_DIRECTORY または Inbox"),
+        tags: z.array(z.string()).optional(),
+        note_type: z.string().optional().describe("例: note / decision / task"),
+    }, async ({ title, content, directory, tags, note_type }) => {
+        const result = await store.writeNote({
+            title,
+            content,
+            directory,
+            tags,
+            noteType: note_type,
+        });
+        const summary = summarizeWriteNoteResponse({
+            operation: result.operation,
+            unresolvedWikiLinkCount: result.unresolvedWikiLinks.length,
+            boundaryWarningCount: result.boundaryWarnings.length,
+            memoryContractStatus: result.memoryContract.status,
+            duplicateWarningCount: result.duplicateWarnings.length,
+            orphanWarning: result.orphanWarning,
+            title: result.title,
+        });
+        const lines = [
+            "ノートを作成/更新しました。",
+            `project: ${result.project}`,
+            `scope_label: ${TOOL_SCOPE_LABELS.write_note}`,
+            `primary_navigation_signal: ${summary.primaryNavigationSignal}`,
+            `primary_quality_signal: ${summary.primaryQualitySignal}`,
+            `next_recommended_action: ${summary.nextRecommendedAction}`,
+            `operation: ${result.operation}`,
+            `file: ${result.relativePath}`,
+            `permalink: ${result.permalink}`,
+            `title: ${result.title}`,
+            `link_health: ${result.linkHealth.resolved}/${result.linkHealth.total} resolved`,
+            `backlinks: ${result.backlinkCount}`,
+            `orphan_warning: ${result.orphanWarning ? "yes" : "no"}`,
+        ];
+        lines.splice(2, 0, ...[
+            `storage_backend: ${config.github ? "github" : "filesystem"}`,
+            `storage_root: ${config.root}`,
+            ...(config.github
+                ? [`storage_repo: ${config.github.owner}/${config.github.repo}`, `storage_branch: ${config.github.branch}`]
+                : []),
+        ]);
+        if (summary.nextRecommendedTarget) {
+            insertBeforeLine(lines, "next_recommended_action:", `next_recommended_target: ${summary.nextRecommendedTarget}`);
+        }
+        appendConflictSummary(lines, summarizeNoConflict({ serverUpdated: result.serverUpdated }));
+        appendResponsibilityWarning(lines, result.boundaryWarnings);
+        appendStructureScore(lines, result.structureScore);
+        appendMemoryContract(lines, result.memoryContract);
+        appendBoundaryWarnings(lines, result.boundaryWarnings);
+        appendTemplateHints(lines, {
+            primary: "stock",
+            alternatives: ["index"],
+            reason: "通常ノートとして知識を残すときは stock template を基準にする",
+            whenToSwitch: "再訪導線を固定したい入口ノートなら index template に切り替える",
+        });
+        appendUnresolvedWikiLinks(lines, result.unresolvedWikiLinks);
+        appendUnresolvedLinkHints(lines, result.unresolvedLinkHints);
+        appendDuplicateWarnings(lines, result.duplicateWarnings);
+        await appendAutoProjectHealth(lines);
+        return textResult(lines.join("\n"));
+    });
+    server.tool("write_flow_note", "flow ノートを構造テンプレート付きで作成/更新します。", {
+        title: z.string().min(1),
+        question: z.string().min(1),
+        next_action: z.string().min(1),
+        parent_stock: z.string().min(1),
+        related: z.array(z.string()).optional().describe("追加の関連リンク先"),
+        details: z.string().optional().describe("## Notes に入れる本文"),
+        directory: z.string().min(1).optional().describe("default: Flow"),
+        tags: z.array(z.string()).optional(),
+        flow_state: z.string().optional().describe("capture / active / blocked / done / promoted / dropped"),
+    }, async ({ title, question, next_action, parent_stock, related, details, directory, tags, flow_state }) => {
+        const result = await store.writeFlowNote({
+            title,
+            question,
+            nextAction: next_action,
+            parentStock: parent_stock,
+            related,
+            details,
+            directory,
+            tags,
+            flowState: flow_state,
+        });
+        const summary = summarizeWriteFlowResponse({
+            operation: result.operation,
+            unresolvedWikiLinkCount: result.unresolvedWikiLinks.length,
+            boundaryWarningCount: result.boundaryWarnings.length,
+            memoryContractStatus: result.memoryContract.status,
+            duplicateWarningCount: result.duplicateWarnings.length,
+            orphanWarning: result.orphanWarning,
+            title: result.title,
+            parentStockResolved: result.parentStockResolved,
+            parentStock: result.parentStock,
+        });
+        const lines = [
+            "flow ノートを作成/更新しました。",
+            `project: ${result.project}`,
+            `scope_label: ${TOOL_SCOPE_LABELS.write_flow_note}`,
+            `primary_navigation_signal: ${summary.primaryNavigationSignal}`,
+            `primary_quality_signal: ${summary.primaryQualitySignal}`,
+            `next_recommended_action: ${summary.nextRecommendedAction}`,
+            `operation: ${result.operation}`,
+            `file: ${result.relativePath}`,
+            `permalink: ${result.permalink}`,
+            `title: ${result.title}`,
+            `flow_state: ${result.flowState}`,
+            `parent_stock: ${result.parentStock}`,
+            `parent_stock_resolved: ${result.parentStockResolved ? "yes" : "no"}`,
+            `link_health: ${result.linkHealth.resolved}/${result.linkHealth.total} resolved`,
+            `backlinks: ${result.backlinkCount}`,
+            `orphan_warning: ${result.orphanWarning ? "yes" : "no"}`,
+        ];
+        lines.splice(2, 0, ...[
+            `storage_backend: ${config.github ? "github" : "filesystem"}`,
+            `storage_root: ${config.root}`,
+            ...(config.github
+                ? [`storage_repo: ${config.github.owner}/${config.github.repo}`, `storage_branch: ${config.github.branch}`]
+                : []),
+        ]);
+        if (summary.nextRecommendedTarget) {
+            insertBeforeLine(lines, "next_recommended_action:", `next_recommended_target: ${summary.nextRecommendedTarget}`);
+        }
+        appendConflictSummary(lines, summarizeNoConflict({ serverUpdated: result.serverUpdated }));
+        appendResponsibilityWarning(lines, result.boundaryWarnings);
+        appendStructureScore(lines, result.structureScore);
+        appendMemoryContract(lines, result.memoryContract);
+        appendBoundaryWarnings(lines, result.boundaryWarnings);
+        appendTemplateHints(lines, {
+            primary: "flow",
+            alternatives: ["stock", "index"],
+            reason: "進行中の問いと next_action を残すときは flow template を基準にする",
+            whenToSwitch: "知識として固まったら stock、再訪入口を作るなら index template を使う",
+        });
+        appendUnresolvedWikiLinks(lines, result.unresolvedWikiLinks);
+        appendUnresolvedLinkHints(lines, result.unresolvedLinkHints);
+        appendDuplicateWarnings(lines, result.duplicateWarnings);
+        await appendAutoProjectHealth(lines);
+        return textResult(lines.join("\n"));
+    });
+    server.tool("promote_to_stock", "flow ノートを stock ノートへ昇格させ、flow 側の状態を promoted に更新します。", {
+        flow_identifier: z.string().min(1),
+        stock_title: z.string().min(1).optional(),
+        directory: z.string().min(1).optional().describe("default: Stock"),
+        tags: z.array(z.string()).optional(),
+        note_type: z.string().optional().describe("default: stock"),
+    }, async ({ flow_identifier, stock_title, directory, tags, note_type }) => {
+        const result = await store.promoteToStock({
+            flowIdentifier: flow_identifier,
+            stockTitle: stock_title,
+            directory,
+            tags,
+            noteType: note_type,
+        });
+        const summary = summarizePromoteResponse({
+            stockTitle: result.stock.title,
+            sourceFlowTitle: result.sourceFlow.title,
+        });
+        const lines = [
+            "flow を stock に昇格しました。",
+            `project: ${result.project}`,
+            `scope_label: ${TOOL_SCOPE_LABELS.promote_to_stock}`,
+            `primary_navigation_signal: ${summary.primaryNavigationSignal}`,
+            `primary_quality_signal: ${summary.primaryQualitySignal}`,
+            `next_recommended_action: ${summary.nextRecommendedAction}`,
+            `source_flow: ${result.sourceFlow.title}`,
+            `source_file: ${result.sourceFlow.relativePath}`,
+            `source_permalink: ${result.sourceFlow.permalink}`,
+            `stock: ${result.stock.title}`,
+            `stock_file: ${result.stock.relativePath}`,
+            `stock_permalink: ${result.stock.permalink}`,
+            `flow_state: ${result.flowState}`,
+        ];
+        lines.splice(2, 0, ...[
+            `storage_backend: ${config.github ? "github" : "filesystem"}`,
+            `storage_root: ${config.root}`,
+            ...(config.github
+                ? [`storage_repo: ${config.github.owner}/${config.github.repo}`, `storage_branch: ${config.github.branch}`]
+                : []),
+        ]);
+        if (summary.nextRecommendedTarget) {
+            insertBeforeLine(lines, "next_recommended_action:", `next_recommended_target: ${summary.nextRecommendedTarget}`);
+        }
+        appendTemplateHints(lines, {
+            primary: "stock",
+            alternatives: ["index"],
+            reason: "昇格後のノートは再利用知識として stock template を基準に保つ",
+            whenToSwitch: "複数ノートの入口にしたいときだけ index template を使う",
+        });
+        await appendAutoProjectHealth(lines);
+        return textResult(lines.join("\n"));
+    });
+    server.tool("append_note", "既存ノートの末尾に追記します。必要なら作成もできます。", {
+        identifier: z.string().min(1),
+        content: z.string().min(1),
+        create_if_missing: z.boolean().optional().describe("true ならノート未存在時に作成"),
+        directory: z.string().min(1).optional().describe("create_if_missing=true 時の作成先"),
+        tags: z.array(z.string()).optional().describe("create_if_missing=true 時の tags"),
+        note_type: z.string().optional().describe("create_if_missing=true 時の type"),
+    }, async ({ identifier, content, create_if_missing, directory, tags, note_type }) => {
+        const result = await store.appendNote({
+            identifier,
+            content,
+            createIfMissing: create_if_missing,
+            directory,
+            tags,
+            noteType: note_type,
+        });
+        const summary = summarizeAppendResponse({
+            operation: result.operation,
+            unresolvedWikiLinkCount: result.unresolvedWikiLinks.length,
+            boundaryWarningCount: result.boundaryWarnings.length,
+            memoryContractStatus: result.memoryContract.status,
+            duplicateWarningCount: result.duplicateWarnings.length,
+            orphanWarning: result.orphanWarning,
+            title: result.title,
+        });
+        const lines = [
+            "ノートを処理しました。",
+            `project: ${result.project}`,
+            `scope_label: ${TOOL_SCOPE_LABELS.append_note}`,
+            `primary_navigation_signal: ${summary.primaryNavigationSignal}`,
+            `primary_quality_signal: ${summary.primaryQualitySignal}`,
+            `next_recommended_action: ${summary.nextRecommendedAction}`,
+            `operation: ${result.operation}`,
+            `file: ${result.relativePath}`,
+            `permalink: ${result.permalink}`,
+            `title: ${result.title}`,
+            `link_health: ${result.linkHealth.resolved}/${result.linkHealth.total} resolved`,
+            `backlinks: ${result.backlinkCount}`,
+            `orphan_warning: ${result.orphanWarning ? "yes" : "no"}`,
+        ];
+        lines.splice(2, 0, ...[
+            `storage_backend: ${config.github ? "github" : "filesystem"}`,
+            `storage_root: ${config.root}`,
+            ...(config.github
+                ? [`storage_repo: ${config.github.owner}/${config.github.repo}`, `storage_branch: ${config.github.branch}`]
+                : []),
+        ]);
+        if (summary.nextRecommendedTarget) {
+            insertBeforeLine(lines, "next_recommended_action:", `next_recommended_target: ${summary.nextRecommendedTarget}`);
+        }
+        appendConflictSummary(lines, summarizeNoConflict({ serverUpdated: result.serverUpdated }));
+        appendResponsibilityWarning(lines, result.boundaryWarnings);
+        appendStructureScore(lines, result.structureScore);
+        appendMemoryContract(lines, result.memoryContract);
+        appendBoundaryWarnings(lines, result.boundaryWarnings);
+        if (result.operation === "created") {
+            appendTemplateHints(lines, {
+                primary: "stock",
+                alternatives: ["index"],
+                reason: "新規作成ノートとしては stock template が最小の出発点になる",
+                whenToSwitch: "入口ノートとして作るなら index template に切り替える",
+            });
+        }
+        appendUnresolvedWikiLinks(lines, result.unresolvedWikiLinks);
+        appendUnresolvedLinkHints(lines, result.unresolvedLinkHints);
+        appendDuplicateWarnings(lines, result.duplicateWarnings);
+        await appendAutoProjectHealth(lines);
+        return textResult(lines.join("\n"));
+    });
+    server.tool("delete_note", "ノートを削除します。削除影響のリンク情報も返します。", {
+        identifier: z.string().min(1),
+    }, async ({ identifier }) => {
+        const result = await store.deleteNote({
+            identifier,
+        });
+        const projectUnresolvedDelta = result.projectLinkHealthAfter.unresolved - result.projectLinkHealthBefore.unresolved;
+        const impact = summarizeDeleteImpact({
+            projectUnresolvedDelta,
+            backlinksToDeleted: result.backlinksToDeleted,
+        });
+        const summary = summarizeDeleteResponse({
+            unresolvedWikiLinkCount: result.unresolvedWikiLinks.length,
+            projectUnresolvedDelta,
+            backlinksToDeleted: result.backlinksToDeleted,
+            deletedTitle: result.title,
+        });
+        const lines = [
+            "ノートを削除しました。",
+            `project: ${result.project}`,
+            `scope_label: ${TOOL_SCOPE_LABELS.delete_note}`,
+            `primary_navigation_signal: ${summary.primaryNavigationSignal}`,
+            `primary_quality_signal: ${summary.primaryQualitySignal}`,
+            `next_recommended_action: ${summary.nextRecommendedAction}`,
+            `deleted: ${result.title} (${result.relativePath})`,
+            `permalink: ${result.permalink}`,
+            `backlinks_to_deleted: ${result.backlinksToDeleted}`,
+            `deleted_note_link_health_before: ${result.deletedNoteLinkHealth.resolved}/${result.deletedNoteLinkHealth.total}`,
+            `project_link_health_before: ${result.projectLinkHealthBefore.resolved}/${result.projectLinkHealthBefore.total}`,
+            `project_link_health_after: ${result.projectLinkHealthAfter.resolved}/${result.projectLinkHealthAfter.total}`,
+            `project_unresolved_delta: ${projectUnresolvedDelta}`,
+        ];
+        lines.splice(2, 0, ...[
+            `storage_backend: ${config.github ? "github" : "filesystem"}`,
+            `storage_root: ${config.root}`,
+            ...(config.github
+                ? [`storage_repo: ${config.github.owner}/${config.github.repo}`, `storage_branch: ${config.github.branch}`]
+                : []),
+        ]);
+        if (summary.nextRecommendedTarget) {
+            insertBeforeLine(lines, "next_recommended_action:", `next_recommended_target: ${summary.nextRecommendedTarget}`);
+        }
+        appendConflictSummary(lines, summarizeNoConflict({ serverUpdated: result.serverUpdated }));
+        appendOperationImpact(lines, impact);
+        appendStructureScore(lines, result.structureScoreBeforeDelete);
+        appendMemoryContract(lines, result.memoryContractBeforeDelete);
+        appendUnresolvedWikiLinks(lines, result.unresolvedWikiLinks);
+        appendUnresolvedLinkHints(lines, result.unresolvedLinkHints);
+        await appendAutoProjectHealth(lines);
+        return textResult(lines.join("\n"));
+    });
+    server.tool("rename_note", "ノートをリネームし、必要に応じて WikiLink 参照を追従更新します。", {
+        identifier: z.string().min(1),
+        new_title: z.string().min(1),
+        directory: z.string().min(1).optional().describe("新しい相対ディレクトリ"),
+        update_links: z.boolean().optional().describe("default: true"),
+    }, async ({ identifier, new_title, directory, update_links }) => {
+        const result = await store.renameNote({
+            identifier,
+            newTitle: new_title,
+            directory,
+            updateLinks: update_links,
+        });
+        const projectUnresolvedDelta = result.projectLinkHealthAfter.unresolved - result.projectLinkHealthBefore.unresolved;
+        const impact = summarizeRenameImpact({
+            projectUnresolvedDelta,
+            updatedLinks: result.updatedLinks,
+            updatedFiles: result.updatedFiles,
+            backlinkCount: result.backlinkCount,
+        });
+        const summary = summarizeRenameResponse({
+            unresolvedWikiLinkCount: result.unresolvedWikiLinks.length,
+            boundaryWarningCount: 0,
+            memoryContractStatus: result.memoryContract.status,
+            duplicateWarningCount: 0,
+            orphanWarning: result.orphanWarning,
+            title: result.oldTitle,
+            updatedLinks: result.updatedLinks,
+            newTitle: result.newTitle,
+            projectUnresolvedDelta,
+        });
+        const lines = [
+            "ノートをリネームしました。",
+            `project: ${result.project}`,
+            `scope_label: ${TOOL_SCOPE_LABELS.rename_note}`,
+            `primary_navigation_signal: ${summary.primaryNavigationSignal}`,
+            `primary_quality_signal: ${summary.primaryQualitySignal}`,
+            `next_recommended_action: ${summary.nextRecommendedAction}`,
+            `old: ${result.oldTitle} (${result.oldRelativePath})`,
+            `new: ${result.newTitle} (${result.newRelativePath})`,
+            `links_updated: ${result.updatedLinks}`,
+            `files_updated: ${result.updatedFiles}`,
+            `renamed_note_link_health: ${result.renamedNoteLinkHealth.resolved}/${result.renamedNoteLinkHealth.total}`,
+            `backlinks: ${result.backlinkCount}`,
+            `orphan_warning: ${result.orphanWarning ? "yes" : "no"}`,
+            `project_link_health_before: ${result.projectLinkHealthBefore.resolved}/${result.projectLinkHealthBefore.total}`,
+            `project_link_health_after: ${result.projectLinkHealthAfter.resolved}/${result.projectLinkHealthAfter.total}`,
+            `project_unresolved_delta: ${projectUnresolvedDelta}`,
+        ];
+        lines.splice(2, 0, ...[
+            `storage_backend: ${config.github ? "github" : "filesystem"}`,
+            `storage_root: ${config.root}`,
+            ...(config.github
+                ? [`storage_repo: ${config.github.owner}/${config.github.repo}`, `storage_branch: ${config.github.branch}`]
+                : []),
+        ]);
+        if (summary.nextRecommendedTarget) {
+            insertBeforeLine(lines, "next_recommended_action:", `next_recommended_target: ${summary.nextRecommendedTarget}`);
+        }
+        appendConflictSummary(lines, summarizeNoConflict({ serverUpdated: result.serverUpdated }));
+        appendOperationImpact(lines, impact);
+        appendStructureScore(lines, result.structureScore);
+        appendMemoryContract(lines, result.memoryContract);
+        appendUnresolvedWikiLinks(lines, result.unresolvedWikiLinks);
+        appendUnresolvedLinkHints(lines, result.unresolvedLinkHints);
+        await appendAutoProjectHealth(lines);
+        return textResult(lines.join("\n"));
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("[kioq] failed to start", error);
+    process.exit(1);
+});