@getnote/mcp 1.8.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -131,14 +131,32 @@ function snowflakeID(value, field) {
131
131
  throw new Error(`${field} must be a decimal string; only legacy integers within JavaScript's safe range are accepted`);
132
132
  }
133
133
  // ─── Tool Definitions ────────────────────────────────────────────────────────
134
+ const noteDiscoveryProperties = {
135
+ page: { type: "integer", minimum: 1, description: "知识库内可用页码;与 cursor 互斥" },
136
+ source: { type: "string", description: "来源平台精确筛选,如 dedao" },
137
+ note_type: { type: "string", description: "笔记真实类型精确筛选,如 ref" },
138
+ reference_resource_type: { type: "string", description: "引用资源类型,如 ebook、course_article、audio_book" },
139
+ reference_resource_id: { type: "string", description: "引用资源 ID,必须字符串;同时传 source 和 reference_resource_type" },
140
+ reference_article_url: { type: "string", description: "文章 URL 精确筛选,保留 query 和 fragment" },
141
+ topic_id: { type: "string", description: "知识库 ID,限定授权范围" },
142
+ page_size: { type: "integer", minimum: 1, maximum: 100, description: "每页 1–100 条,默认 20" },
143
+ ...Object.fromEntries(["created_from", "created_to", "edited_from", "edited_to", "record_updated_from", "record_updated_to"].map(key => [key, { type: "string", description: "RFC3339 带时区,from 包含、to 不包含;三种时间轴独立" }])),
144
+ };
145
+ const knowledgeLookupProperties = {
146
+ query: { type: "string", description: "按知识库名/书名定位;多候选须核对书名、作者和 book_id" },
147
+ author: { type: "string", description: "书籍作者,限 BOOKSPACE" },
148
+ book_id: { type: "string", description: "书籍 ID 字符串,限 BOOKSPACE" },
149
+ page_size: noteDiscoveryProperties.page_size,
150
+ };
134
151
  const TOOLS = [
135
152
  // ── Notes ──
136
153
  {
137
154
  name: "list_notes",
138
- description: "获取笔记列表(每次固定返回 20 条,服务端不支持 limit 参数)。用游标翻页:首次请求不传 cursor;后续把上一次响应返回的 cursor 字段原样传入,直到 has_more 为 false。响应里的 total 是全库笔记总数,不是本页条数。",
155
+ description: "按来源、引用资源或知识库查找笔记。列表只返回定位信息;需要正文和完整元数据时调用 get_note。新查询须核对 meta.capabilities、applied_filters,按 pagination.next_cursor 翻页到 has_more=false 才能说全量完成。total_count=null 表示未知,不能用本页条数代替全库总数。",
139
156
  inputSchema: {
140
157
  type: "object",
141
158
  properties: {
159
+ ...noteDiscoveryProperties,
142
160
  cursor: {
143
161
  type: "string",
144
162
  description: "翻页游标。首次不传;后续将上一次响应的 cursor 字段原样传入即可,无需任何转换。",
@@ -149,7 +167,7 @@ const TOOLS = [
149
167
  },
150
168
  {
151
169
  name: "get_note",
152
- description: "获取指定笔记的详细内容,包括正文、标签、附件、音频转录、网页链接等。\n\n**字段语义说明(AI Agent 重要参考)**:\n`content` 通常是 AI 总结,不一定是原文。不同类型笔记的原文字段如下:\n- 普通文字笔记(plain_text):原文 = `note.content`\n- 链接/网页笔记(link):原文 = `note.web_page.content`,AI 总结 = `note.content`\n- 录音笔记(audio/local_audio 等):转写原文 = `note.audio.original`,AI 总结 = `note.content`\n\n用户要求'读原文'时,先看 `note.note_type`,再按上述对应关系取字段。",
170
+ description: "获取指定笔记的详细内容,包括正文、标签、附件、音频转录、网页链接等。\n\n**字段语义说明(AI Agent 重要参考)**:\n`content` 通常是 AI 总结,不一定是原文。不同类型笔记的原文字段如下:\n- 引用笔记(ref):原文 = `note.ref_content`,`note.content` 是个人评论\n- 普通文字笔记(plain_text):原文 = `note.content`\n- 链接/网页笔记(link):原文 = `note.web_page.content`,AI 总结 = `note.content`\n- 录音笔记(audio/local_audio):转写原文 = `note.audio.original`,AI 总结 = `note.content`\n\n用户要求'读原文'时,先看 `note.note_type`,再按上述对应关系取字段。",
153
171
  inputSchema: {
154
172
  type: "object",
155
173
  properties: {
@@ -168,7 +186,7 @@ const TOOLS = [
168
186
  },
169
187
  {
170
188
  name: "get_note_original",
171
- description: "直接读取笔记原文。链接笔记返回网页原文,录音笔记返回转写原文,文字笔记返回正文;不要把 AI 摘要冒充原文。",
189
+ description: "直接读取笔记原文。引用笔记返回 ref_content,链接笔记返回网页原文,录音笔记返回转写原文,文字笔记返回正文;无原文或不支持的类型会报错。",
172
190
  inputSchema: { type: "object", properties: { id: { type: ["string", "number"], description: "笔记 ID,推荐十进制字符串" } }, required: ["id"] },
173
191
  },
174
192
  {
@@ -351,6 +369,7 @@ const TOOLS = [
351
369
  inputSchema: {
352
370
  type: "object",
353
371
  properties: {
372
+ ...knowledgeLookupProperties,
354
373
  page: {
355
374
  type: "number",
356
375
  description: "页码,从 1 开始(默认 1)",
@@ -390,10 +409,11 @@ const TOOLS = [
390
409
  },
391
410
  {
392
411
  name: "list_topic_notes",
393
- description: "获取指定知识库内的笔记列表(每页 20 条)。\n\n**AI Agent 提示**:列表返回的 `content` 字段可能较长且通常为 AI 总结。如需先获取标题和类型再按需读详情,可用此接口获取 `note_id` 列表,再对感兴趣的条目逐一调用 `get_note`。",
412
+ description: "列出知识库内可访问的笔记,支持来源、引用资源、时间筛选。列表只返回定位信息;需要正文和完整元数据时调用 get_note。按 pagination.next_page 翻页;去重 ID,重复游标/页码、无进展或中途失败不能声称全量完成。",
394
413
  inputSchema: {
395
414
  type: "object",
396
415
  properties: {
416
+ ...noteDiscoveryProperties,
397
417
  topic_id: {
398
418
  type: "string",
399
419
  description: "知识库 ID",
@@ -710,6 +730,7 @@ const TOOLS = [
710
730
  inputSchema: {
711
731
  type: "object",
712
732
  properties: {
733
+ ...knowledgeLookupProperties,
713
734
  page: {
714
735
  type: "number",
715
736
  description: "页码,从 1 开始,默认 1",
@@ -783,7 +804,7 @@ async function handleTool(name, input, client) {
783
804
  // ── Notes ──
784
805
  case "list_notes": {
785
806
  const cursor = input.cursor;
786
- return client.listNotes({ cursor: cursor === "0" ? undefined : cursor });
807
+ return client.listNotes({ ...input, cursor: cursor === "0" ? undefined : cursor });
787
808
  }
788
809
  case "get_note": {
789
810
  return client.getNote(snowflakeID(input.id, "id"), input.image_quality);
@@ -791,10 +812,31 @@ async function handleTool(name, input, client) {
791
812
  case "get_note_original": {
792
813
  const result = await client.getNote(snowflakeID(input.id, "id"));
793
814
  const note = result.note;
794
- const original = note.web_page?.content || note.audio?.original || note.content;
815
+ let original;
816
+ let original_source;
817
+ switch (note.note_type) {
818
+ case "ref":
819
+ original = note.ref_content;
820
+ original_source = "ref_content";
821
+ break;
822
+ case "plain_text":
823
+ original = note.content;
824
+ original_source = "content";
825
+ break;
826
+ case "link":
827
+ original = note.web_page?.content;
828
+ original_source = "web_page.content";
829
+ break;
830
+ case "audio":
831
+ case "local_audio":
832
+ original = note.audio?.original;
833
+ original_source = "audio.original";
834
+ break;
835
+ default: throw new Error(`Unsupported note type for original content: ${note.note_type}`);
836
+ }
795
837
  if (!original)
796
838
  throw new Error("Original content is not available for this note");
797
- return { id: note.id, note_type: note.note_type, title: note.title, original };
839
+ return { id: note.id, note_type: note.note_type, title: note.title, original, original_source };
798
840
  }
799
841
  case "get_note_transcript": {
800
842
  const result = await client.getNote(snowflakeID(input.id, "id"));
@@ -883,6 +925,7 @@ async function handleTool(name, input, client) {
883
925
  // ── Knowledge ──
884
926
  case "list_topics": {
885
927
  return client.listTopics({
928
+ ...input,
886
929
  page: input.page,
887
930
  scope: input.scope,
888
931
  });
@@ -896,6 +939,7 @@ async function handleTool(name, input, client) {
896
939
  }
897
940
  case "list_topic_notes": {
898
941
  return client.listTopicNotes({
942
+ ...input,
899
943
  topic_id: input.topic_id,
900
944
  page: input.page,
901
945
  });
@@ -1017,6 +1061,7 @@ async function handleTool(name, input, client) {
1017
1061
  // ── Knowledge / Subscribe ──
1018
1062
  case "list_subscribe_topics": {
1019
1063
  return client.listSubscribeTopics({
1064
+ ...input,
1020
1065
  page: input.page,
1021
1066
  scope: input.scope,
1022
1067
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@getnote/mcp",
3
- "version": "1.8.0",
3
+ "version": "1.9.0",
4
4
  "description": "MCP server for 得到大脑(Get笔记) — manage notes and knowledge bases from AI assistants",
5
5
  "main": "dist/index.js",
6
6
  "bin": {
package/src/client.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import axios, { AxiosInstance, AxiosError } from "axios";
2
+ import { discoveryContract, verifyDiscovery, NoteDiscoveryOptions, LookupOptions, DiscoveryKind } from "./discovery";
2
3
 
3
4
  const DEFAULT_BASE_URL = "https://openapi.biji.com/open/api/v1";
4
5
 
@@ -21,12 +22,11 @@ function normalizeBaseURL(value?: string): string {
21
22
  */
22
23
  export function parseJsonPreservingLargeIntegerStrings(data: unknown) {
23
24
  if (typeof data !== "string" || data.trim() === "") return data;
25
+ // Match complete JSON strings first so numeric text inside note bodies is
26
+ // never rewritten. Consume full number tokens to preserve decimals/exponents.
24
27
  const safe = data.replace(
25
- /"(note_id|next_cursor|cursor|id|parent_id|topic_id|since_id|share_id|follow_id|live_id)"\s*:\s*(\d{16,})/g,
26
- '"$1":"$2"'
27
- ).replace(
28
- /([:[,]\s*)(-?\d{16,})(?=\s*[,}\]])/g,
29
- '$1"$2"'
28
+ /"(?:\\[\s\S]|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g,
29
+ token => /^-?\d{16,}$/.test(token) ? JSON.stringify(token) : token
30
30
  );
31
31
  return JSON.parse(safe);
32
32
  }
@@ -94,10 +94,14 @@ export class GetNoteClient {
94
94
  params?: Record<string, unknown>,
95
95
  data?: unknown
96
96
  ): Promise<T> {
97
+ const kinds: Record<string, DiscoveryKind> = { "/resource/note/list": "notes", "/resource/note/detail": "detail", "/resource/knowledge/notes": "topicNotes", "/resource/knowledge/list": "topics", "/resource/knowledge/subscribe/list": "topics" };
98
+ const contract = method === "GET" && kinds[path] ? discoveryContract(kinds[path], params || {}) : undefined;
99
+ if (contract) params = contract.params;
97
100
  try {
98
101
  const res = await this.http.request<{
99
102
  success: boolean;
100
103
  data: T;
104
+ meta?: { capabilities?: string[]; [key: string]: unknown };
101
105
  error?: APIErrorBody;
102
106
  request_id?: string;
103
107
  }>({
@@ -122,6 +126,11 @@ export class GetNoteClient {
122
126
  );
123
127
  }
124
128
 
129
+ if (contract) verifyDiscovery(body, contract);
130
+ // Keep the verified envelope capabilities visible to the Agent.
131
+ if (body.meta?.capabilities && typeof body.data === "object" && body.data !== null && !Array.isArray(body.data)) {
132
+ return { ...body.data, meta: body.meta };
133
+ }
125
134
  return body.data;
126
135
  } catch (err) {
127
136
  if (err instanceof GetNoteAPIError) throw err;
@@ -153,10 +162,8 @@ export class GetNoteClient {
153
162
 
154
163
  // ─── Notes ───────────────────────────────────────────────────────────────
155
164
 
156
- async listNotes(params: { cursor?: string }) {
157
- return this.request<ListNotesResp>("GET", "/resource/note/list", {
158
- ...(params.cursor ? { cursor: params.cursor } : {}),
159
- });
165
+ async listNotes(params: NoteDiscoveryOptions) {
166
+ return this.request<ListNotesResp>("GET", "/resource/note/list", { ...params });
160
167
  }
161
168
 
162
169
  async getNote(id: string | number, image_quality?: string) {
@@ -289,9 +296,9 @@ export class GetNoteClient {
289
296
 
290
297
  // ─── Knowledge / Topics ─────────────────────────────────────────────────
291
298
 
292
- async listTopics(params?: { page?: number; scope?: KnowledgeScope }) {
299
+ async listTopics(params?: LookupOptions) {
293
300
  return this.request<ListTopicsResp>("GET", "/resource/knowledge/list", {
294
- page: params?.page,
301
+ ...params,
295
302
  scope: params?.scope ?? "DEFAULT",
296
303
  });
297
304
  }
@@ -305,11 +312,11 @@ export class GetNoteClient {
305
312
  );
306
313
  }
307
314
 
308
- async listTopicNotes(params: { topic_id: string; page?: number }) {
315
+ async listTopicNotes(params: NoteDiscoveryOptions & { topic_id: string }) {
309
316
  return this.request<ListTopicNotesResp>(
310
317
  "GET",
311
318
  "/resource/knowledge/notes",
312
- { topic_id: params.topic_id, page: params.page }
319
+ { ...params }
313
320
  );
314
321
  }
315
322
 
@@ -422,11 +429,11 @@ export class GetNoteClient {
422
429
  );
423
430
  }
424
431
 
425
- async listSubscribeTopics(params: { page?: number; scope?: KnowledgeScope }) {
432
+ async listSubscribeTopics(params: LookupOptions) {
426
433
  return this.request<ListSubscribeTopicsResp>(
427
434
  "GET",
428
435
  "/resource/knowledge/subscribe/list",
429
- { page: params.page, scope: params.scope ?? "DEFAULT" }
436
+ { ...params, scope: params.scope ?? "DEFAULT" }
430
437
  );
431
438
  }
432
439
 
@@ -455,21 +462,44 @@ export interface TagInfo {
455
462
  type: "ai" | "manual" | "system";
456
463
  }
457
464
 
458
- export interface NoteItem {
465
+ export interface NoteReference {
466
+ source: string; resource_type: string; ptype: number; resource_id?: string;
467
+ title?: string; author?: string; url?: string; original_note_id?: string;
468
+ is_source_private: boolean; book_id?: string;
469
+ article?: { title?: string; url?: string };
470
+ location?: { chapter_id?: string; chapter_name?: string; page?: number; start_offset?: number; end_offset?: number };
471
+ }
472
+ export interface BookInfo { book_id: string; title: string; author: string; platform?: string; source?: string; isbn?: string }
473
+ export interface DiscoveryMetadata {
474
+ display_title?: string;
475
+ reference?: NoteReference;
476
+ timestamps?: { created_at?: string; edited_at?: string; record_updated_at?: string };
477
+ preview?: { text: string; source: string; truncated: boolean };
478
+ content_state?: { content: string; ref_content: string };
479
+ metadata_state?: { reference: string; topics: string };
480
+ }
481
+ export interface DiscoveryResponse {
482
+ meta?: { capabilities: string[]; timestamp?: number };
483
+ pagination?: { mode: "page" | "cursor"; page: number | null; page_size: number; returned_count: number; total_count: number | null; has_more: boolean; next_page: number | null; next_cursor: string | null };
484
+ applied_filters?: Record<string, string>;
485
+ warnings?: unknown[];
486
+ }
487
+
488
+ export interface NoteItem extends DiscoveryMetadata {
459
489
  /**
460
490
  * Note ID. Returned as string because the actual values exceed
461
491
  * Number.MAX_SAFE_INTEGER. See parseJsonPreservingLargeIntegerStrings.
462
492
  */
463
493
  id: string;
464
494
  title: string;
465
- content: string;
495
+ content?: string;
466
496
  ref_content?: string;
467
497
  note_type: string;
468
498
  source: string;
469
499
  tags: TagInfo[];
470
500
  parent_id?: string;
471
501
  children_count?: number;
472
- topics?: { id: string; name: string }[];
502
+ topics?: { id: string; name: string; scope?: string; book_info?: BookInfo }[];
473
503
  is_child_note?: boolean;
474
504
  created_at: string;
475
505
  updated_at: string;
@@ -516,7 +546,7 @@ export interface NoteDetail extends NoteItem {
516
546
  version?: number;
517
547
  }
518
548
 
519
- export interface ListNotesResp {
549
+ export interface ListNotesResp extends DiscoveryResponse {
520
550
  notes: NoteItem[];
521
551
  has_more: boolean;
522
552
  /**
@@ -529,7 +559,7 @@ export interface ListNotesResp {
529
559
  total: number;
530
560
  }
531
561
 
532
- export interface GetNoteResp {
562
+ export interface GetNoteResp extends DiscoveryResponse {
533
563
  note: NoteDetail;
534
564
  }
535
565
 
@@ -644,9 +674,11 @@ export interface KnowledgeTopic {
644
674
  stats?: KnowledgeTopicStats;
645
675
  created_at?: string;
646
676
  updated_at?: string;
677
+ topic_id?: string;
678
+ book_info?: BookInfo;
647
679
  }
648
680
 
649
- export interface ListTopicsResp {
681
+ export interface ListTopicsResp extends DiscoveryResponse {
650
682
  topics: KnowledgeTopic[];
651
683
  has_more: boolean;
652
684
  total: number;
@@ -660,10 +692,12 @@ export interface CreateTopicResp {
660
692
  scope?: string;
661
693
  }
662
694
 
663
- export interface TopicNoteItem {
695
+ export interface TopicNoteItem extends DiscoveryMetadata {
664
696
  note_id: string;
665
697
  title: string;
666
- content: string;
698
+ content?: string;
699
+ ref_content?: string;
700
+ note_url?: string;
667
701
  note_type: string;
668
702
  tags: string[];
669
703
  is_ai_generated?: boolean;
@@ -671,7 +705,7 @@ export interface TopicNoteItem {
671
705
  edit_time: string;
672
706
  }
673
707
 
674
- export interface ListTopicNotesResp {
708
+ export interface ListTopicNotesResp extends DiscoveryResponse {
675
709
  notes: TopicNoteItem[];
676
710
  has_more: boolean;
677
711
  total: number;
@@ -830,7 +864,7 @@ export interface ShareNoteResp {
830
864
 
831
865
  // ─── List Subscribe Topics Types ──────────────────────────────────────────────
832
866
 
833
- export interface ListSubscribeTopicsResp {
867
+ export interface ListSubscribeTopicsResp extends DiscoveryResponse {
834
868
  topics: KnowledgeTopic[];
835
869
  has_more: boolean;
836
870
  total: number;
@@ -864,14 +898,26 @@ export interface UpdateNoteResp {
864
898
  // ─── Recall / Search Types ───────────────────────────────────────────────────
865
899
 
866
900
  export interface RecallResultItem {
867
- note_id: string;
901
+ note_id?: string;
902
+ resource_id?: string;
868
903
  note_type: "NOTE" | "FILE" | "BLOGGER" | "LIVE" | "URL" | "DEDAO";
869
904
  title: string;
870
905
  content: string;
871
906
  created_at: string;
872
907
  page_no?: number;
908
+ resource_type?: string;
909
+ note?: NoteItem;
910
+ note_url?: string;
911
+ snippet?: string;
912
+ snippet_source?: string;
913
+ score?: number | null;
873
914
  }
874
915
 
875
- export interface RecallResp {
916
+ export interface RecallResp extends DiscoveryResponse {
876
917
  results: RecallResultItem[];
918
+ result_mode?: string;
919
+ is_exhaustive?: boolean;
920
+ returned_count?: number;
921
+ distinct_note_count?: number;
922
+ partial?: boolean;
877
923
  }
@@ -0,0 +1,89 @@
1
+ import { z } from "zod";
2
+
3
+ const text = z.string().trim().min(1);
4
+ const integer = z.number().int().positive();
5
+ const times = ["created_from", "created_to", "edited_from", "edited_to", "record_updated_from", "record_updated_to"] as const;
6
+ export const noteSelectors = {
7
+ source: text.optional(), note_type: text.optional(),
8
+ reference_resource_type: text.optional(), reference_resource_id: text.optional(),
9
+ reference_article_url: z.string().url().refine(v => /^https?:\/\//.test(v)).optional(),
10
+ topic_id: text.optional(), page_size: integer.max(100).optional(),
11
+ created_from: text.optional(), created_to: text.optional(), edited_from: text.optional(), edited_to: text.optional(),
12
+ record_updated_from: text.optional(), record_updated_to: text.optional(),
13
+ };
14
+ export type NoteDiscoveryOptions = z.infer<ReturnType<typeof noteSchema>>;
15
+ function noteSchema() { return z.object({ ...noteSelectors, page: integer.optional(), cursor: z.string().min(1).optional() }).strict(); }
16
+ const lookupSchema = z.object({ page: integer.optional(), scope: z.enum(["DEFAULT", "CUSTOMER", "BOOKSPACE", "TEAMSPACE"]).optional(), query: text.optional(), author: text.optional(), book_id: text.optional(), page_size: integer.max(100).optional() }).strict();
17
+ export type LookupOptions = z.infer<typeof lookupSchema>;
18
+ export type DiscoveryKind = "notes" | "topicNotes" | "topics" | "detail";
19
+ export type DiscoveryContract = { params: Record<string, unknown>; filters: Record<string, string>; capabilities: string[]; kind: DiscoveryKind };
20
+
21
+ export function normalizeLookup(value: string): string {
22
+ value = value.normalize("NFKC").trim();
23
+ for (const [left, right] of [["《", "》"], ["“", "”"], ['"', '"'], ["'", "'"]]) {
24
+ if (value.startsWith(left) && value.endsWith(right) && value.length >= left.length + right.length) { value = value.slice(left.length, -right.length).trim(); break; }
25
+ }
26
+ return value.toLowerCase();
27
+ }
28
+
29
+ // Keep nanoseconds: Date alone would round distinct reference/time boundaries.
30
+ function timestamp(value: string): { text: string; epoch: bigint } {
31
+ z.string().datetime({ offset: true }).parse(value);
32
+ const m = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/.exec(value);
33
+ if (!m) throw new Error("time filters require RFC3339 with timezone");
34
+ const ms = Date.parse(m[1] + m[3]);
35
+ if (!Number.isFinite(ms)) throw new Error("invalid time filter");
36
+ const fraction = (m[2] || "").replace(/0+$/, "");
37
+ return { text: new Date(ms).toISOString().slice(0, 19) + (fraction ? "." + fraction : "") + "Z", epoch: BigInt(ms) * 1000000n + BigInt((m[2] || "").padEnd(9, "0")) };
38
+ }
39
+
40
+ export function discoveryContract(kind: DiscoveryKind, input: Record<string, unknown>): DiscoveryContract | undefined {
41
+ const values = Object.fromEntries(Object.entries(input).filter(([, v]) => v !== undefined));
42
+ const legacy = kind === "topics" ? ["page", "scope"] : kind === "detail" ? ["id", "image_quality"] : kind === "topicNotes" ? ["topic_id", "page"] : ["cursor"];
43
+ if (!Object.keys(values).some(k => !legacy.includes(k))) return undefined;
44
+ let params: Record<string, unknown>;
45
+ const filters: Record<string, string> = {};
46
+ if (kind === "detail") {
47
+ params = z.object({ id: z.union([text, z.number().int().safe()]), image_quality: z.enum(["original"]).optional() }).strict().parse(values);
48
+ return { params, filters, capabilities: ["note.reference.v1"], kind };
49
+ }
50
+ if (kind === "topics") {
51
+ params = { scope: "DEFAULT", page: 1, page_size: 20, ...lookupSchema.parse(values) };
52
+ if (params.scope !== "BOOKSPACE" && (params.author || params.book_id)) throw new Error("author and book_id require BOOKSPACE");
53
+ for (const key of ["query", "author"]) if (typeof params[key] === "string") params[key] = normalizeLookup(params[key] as string);
54
+ } else {
55
+ params = { page_size: 20, ...(kind === "topicNotes" ? { page: 1 } : {}), ...noteSchema().parse(values) };
56
+ if (kind === "topicNotes" && !params.topic_id) throw new Error("topic_id is required");
57
+ if (params.page && (!params.topic_id || params.cursor)) throw new Error("page requires topic_id and cannot be combined with cursor");
58
+ if (params.reference_resource_id) {
59
+ if (!params.source || !params.reference_resource_type) throw new Error("reference ID requires source and resource type");
60
+ const id = String(params.reference_resource_id);
61
+ if (!/^\d+$/.test(id) || BigInt(id) <= 0n || BigInt(id) > 9223372036854775807n) throw new Error("invalid reference ID");
62
+ }
63
+ const epochs: Record<string, bigint> = {};
64
+ for (const key of times) if (typeof params[key] === "string") { const t = timestamp(params[key] as string); params[key] = t.text; epochs[key] = t.epoch; }
65
+ for (const prefix of ["created", "edited", "record_updated"]) if (epochs[prefix + "_from"] !== undefined && epochs[prefix + "_to"] !== undefined && epochs[prefix + "_from"] >= epochs[prefix + "_to"]) throw new Error("time interval must have from < to");
66
+ }
67
+ for (const [key, value] of Object.entries(params)) if (!["cursor", "page", "page_size"].includes(key)) filters[key] = String(value);
68
+ const capabilities = ["pagination.v1"];
69
+ if (kind === "topics") capabilities.push("knowledge.lookup.v1");
70
+ else if (Object.keys(filters).length) capabilities.push("note.filters.v1");
71
+ if (kind !== "topics") capabilities.push("note.reference.v1");
72
+ return { params, filters, capabilities, kind };
73
+ }
74
+
75
+ export function verifyDiscovery(body: unknown, contract: DiscoveryContract): void {
76
+ const envelope = z.object({ meta: z.object({ capabilities: z.array(z.string()) }), data: z.record(z.unknown()) }).safeParse(body);
77
+ if (!envelope.success) throw new Error("server does not declare discovery capabilities; upgrade the server (unfiltered results not accepted)");
78
+ for (const cap of contract.capabilities) if (!envelope.data.meta.capabilities.includes(cap)) throw new Error(`server does not support ${cap}; unfiltered results not accepted`);
79
+ if (contract.kind === "detail") return;
80
+ const data = envelope.data.data;
81
+ const applied = z.record(z.string()).safeParse(data.applied_filters);
82
+ if (!applied.success) throw new Error("server did not return applied_filters");
83
+ for (const [key, value] of Object.entries(contract.filters)) if (applied.data[key] !== value) throw new Error(`server did not apply ${key}`);
84
+ const p = z.object({ mode: z.enum(["page", "cursor"]), page: integer.nullable(), page_size: integer.max(100), returned_count: z.number().int().nonnegative(), total_count: z.number().int().nonnegative().nullable(), has_more: z.boolean(), next_page: integer.nullable(), next_cursor: z.string().min(1).nullable() }).parse(data.pagination);
85
+ const items = data[contract.kind === "topics" ? "topics" : "notes"];
86
+ const page = contract.params.page;
87
+ if (!Array.isArray(items) || p.mode !== (page ? "page" : "cursor") || p.page_size !== contract.params.page_size || p.returned_count !== items.length || items.length > p.page_size || (p.total_count !== null && p.total_count < items.length) || (page && p.page !== page)) throw new Error("invalid discovery pagination response");
88
+ if (p.has_more ? (page ? p.next_page !== Number(page) + 1 || p.next_cursor !== null : !p.next_cursor || p.next_page !== null) : p.next_page !== null || p.next_cursor !== null) throw new Error("invalid discovery continuation");
89
+ }
package/src/index.ts CHANGED
@@ -121,15 +121,34 @@ function snowflakeID(value: unknown, field: string): string | number {
121
121
 
122
122
  // ─── Tool Definitions ────────────────────────────────────────────────────────
123
123
 
124
+ const noteDiscoveryProperties = {
125
+ page: { type: "integer", minimum: 1, description: "知识库内可用页码;与 cursor 互斥" },
126
+ source: { type: "string", description: "来源平台精确筛选,如 dedao" },
127
+ note_type: { type: "string", description: "笔记真实类型精确筛选,如 ref" },
128
+ reference_resource_type: { type: "string", description: "引用资源类型,如 ebook、course_article、audio_book" },
129
+ reference_resource_id: { type: "string", description: "引用资源 ID,必须字符串;同时传 source 和 reference_resource_type" },
130
+ reference_article_url: { type: "string", description: "文章 URL 精确筛选,保留 query 和 fragment" },
131
+ topic_id: { type: "string", description: "知识库 ID,限定授权范围" },
132
+ page_size: { type: "integer", minimum: 1, maximum: 100, description: "每页 1–100 条,默认 20" },
133
+ ...Object.fromEntries(["created_from", "created_to", "edited_from", "edited_to", "record_updated_from", "record_updated_to"].map(key => [key, { type: "string", description: "RFC3339 带时区,from 包含、to 不包含;三种时间轴独立" }])),
134
+ };
135
+ const knowledgeLookupProperties = {
136
+ query: { type: "string", description: "按知识库名/书名定位;多候选须核对书名、作者和 book_id" },
137
+ author: { type: "string", description: "书籍作者,限 BOOKSPACE" },
138
+ book_id: { type: "string", description: "书籍 ID 字符串,限 BOOKSPACE" },
139
+ page_size: noteDiscoveryProperties.page_size,
140
+ };
141
+
124
142
  const TOOLS: Tool[] = [
125
143
  // ── Notes ──
126
144
  {
127
145
  name: "list_notes",
128
146
  description:
129
- "获取笔记列表(每次固定返回 20 条,服务端不支持 limit 参数)。用游标翻页:首次请求不传 cursor;后续把上一次响应返回的 cursor 字段原样传入,直到 has_more 为 false。响应里的 total 是全库笔记总数,不是本页条数。",
147
+ "按来源、引用资源或知识库查找笔记。列表只返回定位信息;需要正文和完整元数据时调用 get_note。新查询须核对 meta.capabilities、applied_filters,按 pagination.next_cursor 翻页到 has_more=false 才能说全量完成。total_count=null 表示未知,不能用本页条数代替全库总数。",
130
148
  inputSchema: {
131
149
  type: "object" as const,
132
150
  properties: {
151
+ ...noteDiscoveryProperties,
133
152
  cursor: {
134
153
  type: "string",
135
154
  description: "翻页游标。首次不传;后续将上一次响应的 cursor 字段原样传入即可,无需任何转换。",
@@ -140,7 +159,7 @@ const TOOLS: Tool[] = [
140
159
  },
141
160
  {
142
161
  name: "get_note",
143
- description: "获取指定笔记的详细内容,包括正文、标签、附件、音频转录、网页链接等。\n\n**字段语义说明(AI Agent 重要参考)**:\n`content` 通常是 AI 总结,不一定是原文。不同类型笔记的原文字段如下:\n- 普通文字笔记(plain_text):原文 = `note.content`\n- 链接/网页笔记(link):原文 = `note.web_page.content`,AI 总结 = `note.content`\n- 录音笔记(audio/local_audio 等):转写原文 = `note.audio.original`,AI 总结 = `note.content`\n\n用户要求'读原文'时,先看 `note.note_type`,再按上述对应关系取字段。",
162
+ description: "获取指定笔记的详细内容,包括正文、标签、附件、音频转录、网页链接等。\n\n**字段语义说明(AI Agent 重要参考)**:\n`content` 通常是 AI 总结,不一定是原文。不同类型笔记的原文字段如下:\n- 引用笔记(ref):原文 = `note.ref_content`,`note.content` 是个人评论\n- 普通文字笔记(plain_text):原文 = `note.content`\n- 链接/网页笔记(link):原文 = `note.web_page.content`,AI 总结 = `note.content`\n- 录音笔记(audio/local_audio):转写原文 = `note.audio.original`,AI 总结 = `note.content`\n\n用户要求'读原文'时,先看 `note.note_type`,再按上述对应关系取字段。",
144
163
  inputSchema: {
145
164
  type: "object" as const,
146
165
  properties: {
@@ -159,7 +178,7 @@ const TOOLS: Tool[] = [
159
178
  },
160
179
  {
161
180
  name: "get_note_original",
162
- description: "直接读取笔记原文。链接笔记返回网页原文,录音笔记返回转写原文,文字笔记返回正文;不要把 AI 摘要冒充原文。",
181
+ description: "直接读取笔记原文。引用笔记返回 ref_content,链接笔记返回网页原文,录音笔记返回转写原文,文字笔记返回正文;无原文或不支持的类型会报错。",
163
182
  inputSchema: { type: "object" as const, properties: { id: { type: ["string", "number"], description: "笔记 ID,推荐十进制字符串" } }, required: ["id"] },
164
183
  },
165
184
  {
@@ -347,6 +366,7 @@ const TOOLS: Tool[] = [
347
366
  inputSchema: {
348
367
  type: "object" as const,
349
368
  properties: {
369
+ ...knowledgeLookupProperties,
350
370
  page: {
351
371
  type: "number",
352
372
  description: "页码,从 1 开始(默认 1)",
@@ -386,10 +406,11 @@ const TOOLS: Tool[] = [
386
406
  },
387
407
  {
388
408
  name: "list_topic_notes",
389
- description: "获取指定知识库内的笔记列表(每页 20 条)。\n\n**AI Agent 提示**:列表返回的 `content` 字段可能较长且通常为 AI 总结。如需先获取标题和类型再按需读详情,可用此接口获取 `note_id` 列表,再对感兴趣的条目逐一调用 `get_note`。",
409
+ description: "列出知识库内可访问的笔记,支持来源、引用资源、时间筛选。列表只返回定位信息;需要正文和完整元数据时调用 get_note。按 pagination.next_page 翻页;去重 ID,重复游标/页码、无进展或中途失败不能声称全量完成。",
390
410
  inputSchema: {
391
411
  type: "object" as const,
392
412
  properties: {
413
+ ...noteDiscoveryProperties,
393
414
  topic_id: {
394
415
  type: "string",
395
416
  description: "知识库 ID",
@@ -724,6 +745,7 @@ const TOOLS: Tool[] = [
724
745
  inputSchema: {
725
746
  type: "object" as const,
726
747
  properties: {
748
+ ...knowledgeLookupProperties,
727
749
  page: {
728
750
  type: "number",
729
751
  description: "页码,从 1 开始,默认 1",
@@ -811,7 +833,7 @@ async function handleTool(
811
833
  // ── Notes ──
812
834
  case "list_notes": {
813
835
  const cursor = (input.cursor as string | undefined);
814
- return client.listNotes({ cursor: cursor === "0" ? undefined : cursor });
836
+ return client.listNotes({ ...input, cursor: cursor === "0" ? undefined : cursor });
815
837
  }
816
838
  case "get_note": {
817
839
  return client.getNote(snowflakeID(input.id, "id"), input.image_quality as string | undefined);
@@ -819,9 +841,18 @@ async function handleTool(
819
841
  case "get_note_original": {
820
842
  const result = await client.getNote(snowflakeID(input.id, "id"));
821
843
  const note = result.note;
822
- const original = note.web_page?.content || note.audio?.original || note.content;
844
+ let original: string | undefined;
845
+ let original_source: string;
846
+ switch (note.note_type) {
847
+ case "ref": original = note.ref_content; original_source = "ref_content"; break;
848
+ case "plain_text": original = note.content; original_source = "content"; break;
849
+ case "link": original = note.web_page?.content; original_source = "web_page.content"; break;
850
+ case "audio":
851
+ case "local_audio": original = note.audio?.original; original_source = "audio.original"; break;
852
+ default: throw new Error(`Unsupported note type for original content: ${note.note_type}`);
853
+ }
823
854
  if (!original) throw new Error("Original content is not available for this note");
824
- return { id: note.id, note_type: note.note_type, title: note.title, original };
855
+ return { id: note.id, note_type: note.note_type, title: note.title, original, original_source };
825
856
  }
826
857
  case "get_note_transcript": {
827
858
  const result = await client.getNote(snowflakeID(input.id, "id"));
@@ -906,6 +937,7 @@ async function handleTool(
906
937
  // ── Knowledge ──
907
938
  case "list_topics": {
908
939
  return client.listTopics({
940
+ ...input,
909
941
  page: input.page as number | undefined,
910
942
  scope: input.scope as "DEFAULT" | "CUSTOMER" | "BOOKSPACE" | "TEAMSPACE" | undefined,
911
943
  });
@@ -919,6 +951,7 @@ async function handleTool(
919
951
  }
920
952
  case "list_topic_notes": {
921
953
  return client.listTopicNotes({
954
+ ...input,
922
955
  topic_id: input.topic_id as string,
923
956
  page: input.page as number | undefined,
924
957
  });
@@ -1046,6 +1079,7 @@ async function handleTool(
1046
1079
  // ── Knowledge / Subscribe ──
1047
1080
  case "list_subscribe_topics": {
1048
1081
  return client.listSubscribeTopics({
1082
+ ...input,
1049
1083
  page: input.page as number | undefined,
1050
1084
  scope: input.scope as "DEFAULT" | "CUSTOMER" | "BOOKSPACE" | "TEAMSPACE" | undefined,
1051
1085
  });
@@ -177,3 +177,16 @@ test("OSS multipart fields use the signed names and order", async () => {
177
177
  server.close();
178
178
  }
179
179
  });
180
+
181
+
182
+ test("large-integer preservation never rewrites JSON-looking note text", () => {
183
+ const text = 'example: [1923625755277351496, -1923625755277351496] and "note_id":1923625755277351496, escaped \\"quote\\"';
184
+ const input = JSON.stringify({content:text,preview:text,nested:{quote:text}}).slice(0,-1)+',"ids":[1923625755277351496,-1923625755277351496],"decimal":1923625755277351.5,"exponent":1923625755277351496e-5}';
185
+ const parsed = parseJsonPreservingLargeIntegerStrings(input);
186
+ assert.equal(parsed.content,text);
187
+ assert.equal(parsed.preview,text);
188
+ assert.equal(parsed.nested.quote,text);
189
+ assert.deepEqual(parsed.ids,["1923625755277351496","-1923625755277351496"]);
190
+ assert.equal(parsed.decimal,1923625755277351.5);
191
+ assert.equal(parsed.exponent,1923625755277351496e-5);
192
+ });