@atikk-co-jp/notion-mcp-server 0.7.0 → 0.8.1

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.
Files changed (134) hide show
  1. package/README.ja.md +3 -2
  2. package/README.md +3 -2
  3. package/dist/src/converters/__tests__/block-to-markdown.test.js +482 -111
  4. package/dist/src/converters/__tests__/markdown-to-blocks.test.js +116 -13
  5. package/dist/src/converters/__tests__/page-to-markdown.test.js +83 -70
  6. package/dist/src/converters/__tests__/rich-text-to-markdown.test.js +23 -26
  7. package/dist/src/converters/block-to-markdown.d.ts +4 -13
  8. package/dist/src/converters/block-to-markdown.d.ts.map +1 -1
  9. package/dist/src/converters/block-to-markdown.js +117 -120
  10. package/dist/src/converters/index.d.ts +3 -3
  11. package/dist/src/converters/index.d.ts.map +1 -1
  12. package/dist/src/converters/index.js +1 -1
  13. package/dist/src/converters/markdown-to-blocks.d.ts +21 -7
  14. package/dist/src/converters/markdown-to-blocks.d.ts.map +1 -1
  15. package/dist/src/converters/markdown-to-blocks.js +56 -0
  16. package/dist/src/converters/page-to-markdown.d.ts +5 -20
  17. package/dist/src/converters/page-to-markdown.d.ts.map +1 -1
  18. package/dist/src/converters/page-to-markdown.js +47 -37
  19. package/dist/src/converters/rich-text-to-markdown.d.ts +3 -47
  20. package/dist/src/converters/rich-text-to-markdown.d.ts.map +1 -1
  21. package/dist/src/converters/rich-text-to-markdown.js +15 -14
  22. package/dist/src/notion-client.d.ts +5 -177
  23. package/dist/src/notion-client.d.ts.map +1 -1
  24. package/dist/src/notion-client.js +6 -172
  25. package/dist/src/schemas/descriptions/examples.d.ts +14 -0
  26. package/dist/src/schemas/descriptions/examples.d.ts.map +1 -0
  27. package/dist/src/schemas/descriptions/examples.js +87 -0
  28. package/dist/src/schemas/descriptions/fields.d.ts +146 -0
  29. package/dist/src/schemas/descriptions/fields.d.ts.map +1 -0
  30. package/dist/src/schemas/descriptions/fields.js +184 -0
  31. package/dist/src/schemas/descriptions/index.d.ts +3 -0
  32. package/dist/src/schemas/descriptions/index.d.ts.map +1 -0
  33. package/dist/src/schemas/descriptions/index.js +2 -0
  34. package/dist/src/schemas/index.d.ts +1 -5
  35. package/dist/src/schemas/index.d.ts.map +1 -1
  36. package/dist/src/schemas/index.js +2 -10
  37. package/dist/src/tools/__tests__/context-size.test.d.ts +2 -0
  38. package/dist/src/tools/__tests__/context-size.test.d.ts.map +1 -0
  39. package/dist/src/tools/__tests__/context-size.test.js +143 -0
  40. package/dist/src/tools/__tests__/error-handler.test.d.ts +2 -0
  41. package/dist/src/tools/__tests__/error-handler.test.d.ts.map +1 -0
  42. package/dist/src/tools/__tests__/error-handler.test.js +125 -0
  43. package/dist/src/tools/append-block-children.d.ts.map +1 -1
  44. package/dist/src/tools/append-block-children.js +8 -5
  45. package/dist/src/tools/append-blocks-simple.d.ts.map +1 -1
  46. package/dist/src/tools/append-blocks-simple.js +9 -13
  47. package/dist/src/tools/archive-database.d.ts.map +1 -1
  48. package/dist/src/tools/archive-database.js +3 -2
  49. package/dist/src/tools/archive-page.d.ts.map +1 -1
  50. package/dist/src/tools/archive-page.js +2 -1
  51. package/dist/src/tools/create-comment-simple.d.ts.map +1 -1
  52. package/dist/src/tools/create-comment-simple.js +5 -4
  53. package/dist/src/tools/create-comment.d.ts.map +1 -1
  54. package/dist/src/tools/create-comment.js +9 -6
  55. package/dist/src/tools/create-database.d.ts.map +1 -1
  56. package/dist/src/tools/create-database.js +19 -25
  57. package/dist/src/tools/create-page-simple.d.ts +1 -1
  58. package/dist/src/tools/create-page-simple.d.ts.map +1 -1
  59. package/dist/src/tools/create-page-simple.js +26 -27
  60. package/dist/src/tools/create-page.d.ts.map +1 -1
  61. package/dist/src/tools/create-page.js +10 -6
  62. package/dist/src/tools/delete-block.d.ts.map +1 -1
  63. package/dist/src/tools/delete-block.js +2 -1
  64. package/dist/src/tools/get-block-children.d.ts +1 -1
  65. package/dist/src/tools/get-block-children.d.ts.map +1 -1
  66. package/dist/src/tools/get-block-children.js +13 -27
  67. package/dist/src/tools/index.d.ts +2 -2
  68. package/dist/src/tools/index.d.ts.map +1 -1
  69. package/dist/src/tools/index.js +2 -2
  70. package/dist/src/tools/list-comments.d.ts +1 -1
  71. package/dist/src/tools/list-comments.d.ts.map +1 -1
  72. package/dist/src/tools/list-comments.js +11 -10
  73. package/dist/src/tools/list-users.d.ts.map +1 -1
  74. package/dist/src/tools/list-users.js +4 -3
  75. package/dist/src/tools/move-page.d.ts.map +1 -1
  76. package/dist/src/tools/move-page.js +5 -4
  77. package/dist/src/tools/query-data-source.d.ts +1 -1
  78. package/dist/src/tools/query-data-source.d.ts.map +1 -1
  79. package/dist/src/tools/query-data-source.js +23 -30
  80. package/dist/src/tools/retrieve-block.d.ts +1 -1
  81. package/dist/src/tools/retrieve-block.d.ts.map +1 -1
  82. package/dist/src/tools/retrieve-block.js +13 -10
  83. package/dist/src/tools/retrieve-bot-user.js +1 -1
  84. package/dist/src/tools/retrieve-data-source.d.ts +1 -1
  85. package/dist/src/tools/retrieve-data-source.d.ts.map +1 -1
  86. package/dist/src/tools/retrieve-data-source.js +15 -11
  87. package/dist/src/tools/retrieve-database.d.ts +1 -1
  88. package/dist/src/tools/retrieve-database.d.ts.map +1 -1
  89. package/dist/src/tools/retrieve-database.js +11 -6
  90. package/dist/src/tools/retrieve-page-property.d.ts.map +1 -1
  91. package/dist/src/tools/retrieve-page-property.js +6 -5
  92. package/dist/src/tools/retrieve-page.d.ts +1 -1
  93. package/dist/src/tools/retrieve-page.d.ts.map +1 -1
  94. package/dist/src/tools/retrieve-page.js +15 -20
  95. package/dist/src/tools/retrieve-user.d.ts.map +1 -1
  96. package/dist/src/tools/retrieve-user.js +2 -1
  97. package/dist/src/tools/search.d.ts.map +1 -1
  98. package/dist/src/tools/search.js +10 -17
  99. package/dist/src/tools/update-block-simple.d.ts +1 -1
  100. package/dist/src/tools/update-block-simple.d.ts.map +1 -1
  101. package/dist/src/tools/update-block-simple.js +14 -4
  102. package/dist/src/tools/update-block.d.ts.map +1 -1
  103. package/dist/src/tools/update-block.js +8 -5
  104. package/dist/src/tools/update-data-source.d.ts.map +1 -1
  105. package/dist/src/tools/update-data-source.js +7 -7
  106. package/dist/src/tools/update-database.d.ts.map +1 -1
  107. package/dist/src/tools/update-database.js +22 -32
  108. package/dist/src/tools/update-page.d.ts.map +1 -1
  109. package/dist/src/tools/update-page.js +11 -8
  110. package/dist/src/utils/error-handler.d.ts +16 -7
  111. package/dist/src/utils/error-handler.d.ts.map +1 -1
  112. package/dist/src/utils/error-handler.js +44 -17
  113. package/dist/src/utils/index.d.ts +1 -1
  114. package/dist/src/utils/index.d.ts.map +1 -1
  115. package/dist/src/utils/index.js +1 -1
  116. package/package.json +2 -1
  117. package/dist/src/schemas/block.d.ts +0 -3787
  118. package/dist/src/schemas/block.d.ts.map +0 -1
  119. package/dist/src/schemas/block.js +0 -402
  120. package/dist/src/schemas/common.d.ts +0 -638
  121. package/dist/src/schemas/common.d.ts.map +0 -1
  122. package/dist/src/schemas/common.js +0 -163
  123. package/dist/src/schemas/database.d.ts +0 -687
  124. package/dist/src/schemas/database.d.ts.map +0 -1
  125. package/dist/src/schemas/database.js +0 -258
  126. package/dist/src/schemas/filter.d.ts +0 -611
  127. package/dist/src/schemas/filter.d.ts.map +0 -1
  128. package/dist/src/schemas/filter.js +0 -222
  129. package/dist/src/schemas/page.d.ts +0 -2607
  130. package/dist/src/schemas/page.d.ts.map +0 -1
  131. package/dist/src/schemas/page.js +0 -328
  132. package/dist/src/schemas/schemas.test.d.ts +0 -2
  133. package/dist/src/schemas/schemas.test.d.ts.map +0 -1
  134. package/dist/src/schemas/schemas.test.js +0 -418
@@ -1,179 +1,13 @@
1
- const NOTION_API_BASE = 'https://api.notion.com/v1';
2
- const NOTION_VERSION = '2025-09-03';
3
- export class NotionClient {
4
- token;
5
- constructor(options) {
6
- this.token = options.token;
7
- }
8
- async request(endpoint, options = {}) {
9
- const { method = 'GET', body, query } = options;
10
- let url = `${NOTION_API_BASE}${endpoint}`;
11
- if (query) {
12
- const params = new URLSearchParams();
13
- for (const [key, value] of Object.entries(query)) {
14
- if (value !== undefined) {
15
- params.set(key, String(value));
16
- }
17
- }
18
- const queryString = params.toString();
19
- if (queryString) {
20
- url += `?${queryString}`;
21
- }
22
- }
23
- const headers = {
24
- Authorization: `Bearer ${this.token}`,
25
- 'Notion-Version': NOTION_VERSION,
26
- 'Content-Type': 'application/json',
27
- };
28
- const response = await fetch(url, {
29
- method,
30
- headers,
31
- body: body ? JSON.stringify(body) : undefined,
32
- });
33
- const data = await response.json();
34
- if (!response.ok) {
35
- const error = data;
36
- throw new Error(`Notion API error: ${error.code} - ${error.message}`);
37
- }
38
- return data;
39
- }
40
- // Pages
41
- pages = {
42
- create: (params) => {
43
- // API 2025-09-03 requires explicit type in parent
44
- let parentWithType;
45
- if ('data_source_id' in params.parent) {
46
- parentWithType = { type: 'data_source_id', data_source_id: params.parent.data_source_id };
47
- }
48
- else if ('database_id' in params.parent) {
49
- parentWithType = { type: 'database_id', database_id: params.parent.database_id };
50
- }
51
- else {
52
- parentWithType = { type: 'page_id', page_id: params.parent.page_id };
53
- }
54
- const body = { ...params, parent: parentWithType };
55
- return this.request('/pages', { method: 'POST', body });
56
- },
57
- retrieve: (params) => {
58
- return this.request(`/pages/${params.page_id}`);
59
- },
60
- update: (params) => {
61
- const { page_id, ...body } = params;
62
- return this.request(`/pages/${page_id}`, { method: 'PATCH', body });
63
- },
64
- retrieveProperty: (params) => {
65
- const { page_id, property_id, ...query } = params;
66
- return this.request(`/pages/${page_id}/properties/${property_id}`, {
67
- query: query,
68
- });
69
- },
70
- move: (params) => {
71
- // API 2025-09-03 requires explicit type in parent
72
- let parentWithType;
73
- if ('data_source_id' in params.parent) {
74
- parentWithType = { type: 'data_source_id', data_source_id: params.parent.data_source_id };
75
- }
76
- else if ('database_id' in params.parent) {
77
- parentWithType = { type: 'database_id', database_id: params.parent.database_id };
78
- }
79
- else {
80
- parentWithType = { type: 'page_id', page_id: params.parent.page_id };
81
- }
82
- return this.request(`/pages/${params.page_id}/move`, { method: 'POST', body: { parent: parentWithType } });
83
- },
84
- };
85
- // Data Sources (new in 2025-09-03)
86
- dataSources = {
87
- retrieve: (params) => {
88
- return this.request(`/data_sources/${params.data_source_id}`);
89
- },
90
- query: (params) => {
91
- const { data_source_id, ...body } = params;
92
- return this.request(`/data_sources/${data_source_id}/query`, { method: 'POST', body });
93
- },
94
- update: (params) => {
95
- const { data_source_id, ...body } = params;
96
- return this.request(`/data_sources/${data_source_id}`, { method: 'PATCH', body });
97
- },
98
- };
99
- // Databases (container operations only in 2025-09-03)
100
- databases = {
101
- create: (params) => {
102
- // API 2025-09-03 requires explicit type in parent
103
- const body = {
104
- ...params,
105
- parent: { type: 'page_id', page_id: params.parent.page_id },
106
- };
107
- return this.request('/databases', { method: 'POST', body });
108
- },
109
- retrieve: (params) => {
110
- return this.request(`/databases/${params.database_id}`);
111
- },
112
- update: (params) => {
113
- const { database_id, ...body } = params;
114
- return this.request(`/databases/${database_id}`, { method: 'PATCH', body });
115
- },
116
- };
117
- // Blocks
118
- blocks = {
119
- retrieve: (params) => {
120
- return this.request(`/blocks/${params.block_id}`);
121
- },
122
- update: (params) => {
123
- const { block_id, ...body } = params;
124
- return this.request(`/blocks/${block_id}`, { method: 'PATCH', body });
125
- },
126
- delete: (params) => {
127
- return this.request(`/blocks/${params.block_id}`, { method: 'DELETE' });
128
- },
129
- children: {
130
- list: (params) => {
131
- const { block_id, ...query } = params;
132
- return this.request(`/blocks/${block_id}/children`, {
133
- query: query,
134
- });
135
- },
136
- append: (params) => {
137
- const { block_id, ...body } = params;
138
- return this.request(`/blocks/${block_id}/children`, { method: 'PATCH', body });
139
- },
140
- },
141
- };
142
- // Comments
143
- comments = {
144
- create: (params) => {
145
- return this.request('/comments', { method: 'POST', body: params });
146
- },
147
- list: (params) => {
148
- return this.request('/comments', {
149
- query: params,
150
- });
151
- },
152
- };
153
- // Users
154
- users = {
155
- list: (params) => {
156
- return this.request('/users', {
157
- query: params,
158
- });
159
- },
160
- retrieve: (params) => {
161
- return this.request(`/users/${params.user_id}`);
162
- },
163
- me: () => {
164
- return this.request('/users/me');
165
- },
166
- };
167
- // Search (filter value changed from 'database' to 'data_source' in 2025-09-03)
168
- search = (params) => {
169
- return this.request('/search', { method: 'POST', body: params || {} });
170
- };
171
- }
1
+ import { Client } from '@notionhq/client';
2
+ // Re-export official SDK Client
3
+ // Re-export helper functions
4
+ // Re-export error types
5
+ export { APIResponseError, Client as NotionClient, collectPaginatedAPI, isFullBlock, isFullComment, isFullDatabase, isFullDataSource, isFullPage, isFullUser, isNotionClientError, iteratePaginatedAPI, } from '@notionhq/client';
172
6
  export function createNotionClient() {
173
7
  const token = process.env.NOTION_TOKEN;
174
8
  if (!token) {
175
9
  throw new Error('NOTION_TOKEN environment variable is required. ' +
176
10
  'Please set it to your Notion integration token.');
177
11
  }
178
- return new NotionClient({ token });
12
+ return new Client({ auth: token });
179
13
  }
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Property format examples for error messages.
3
+ * Minimal JSON format for token efficiency.
4
+ * Co-located with schemas to prevent drift.
5
+ */
6
+ export declare const PagePropertyExamples: Record<string, string>;
7
+ export declare const SchemaPropertyExamples: Record<string, string>;
8
+ export declare const BlockExamples: Record<string, string>;
9
+ export declare const RichTextArrayExample = "[{\"text\":{\"content\":\"Text\"}}]";
10
+ export declare const FilterExamples: Record<string, string>;
11
+ export declare const SortExamples = "[{\"property\":\"Date\",\"direction\":\"descending\"}]";
12
+ export type ExampleType = 'page' | 'schema' | 'block' | 'richTextArray' | 'filter';
13
+ export declare function getExamplesByType(type: ExampleType): string;
14
+ //# sourceMappingURL=examples.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"examples.d.ts","sourceRoot":"","sources":["../../../../src/schemas/descriptions/examples.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAevD,CAAA;AAGD,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAgBzD,CAAA;AAGD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAWhD,CAAA;AAGD,eAAO,MAAM,oBAAoB,wCAAkC,CAAA;AAGnE,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAOjD,CAAA;AAGD,eAAO,MAAM,YAAY,2DAAmD,CAAA;AAG5E,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,eAAe,GAAG,QAAQ,CAAA;AAGlF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAa3D"}
@@ -0,0 +1,87 @@
1
+ /**
2
+ * Property format examples for error messages.
3
+ * Minimal JSON format for token efficiency.
4
+ * Co-located with schemas to prevent drift.
5
+ */
6
+ // Page property value examples (for create-page, update-page)
7
+ export const PagePropertyExamples = {
8
+ title: '{"title":[{"text":{"content":"value"}}]}',
9
+ rich_text: '{"rich_text":[{"text":{"content":"value"}}]}',
10
+ number: '{"number":123}',
11
+ select: '{"select":{"name":"Option"}}',
12
+ multi_select: '{"multi_select":[{"name":"Option"}]}',
13
+ status: '{"status":{"name":"Status"}}',
14
+ date: '{"date":{"start":"2024-01-01"}}',
15
+ checkbox: '{"checkbox":true}',
16
+ url: '{"url":"https://example.com"}',
17
+ email: '{"email":"a@example.com"}',
18
+ phone_number: '{"phone_number":"+1-234-567-8900"}',
19
+ relation: '{"relation":[{"id":"page-id"}]}',
20
+ people: '{"people":[{"id":"user-id"}]}',
21
+ files: '{"files":[{"type":"external","name":"file","external":{"url":"https://..."}}]}',
22
+ };
23
+ // Schema property examples (for create-database, update-data-source)
24
+ export const SchemaPropertyExamples = {
25
+ title: '{"title":{}}',
26
+ rich_text: '{"rich_text":{}}',
27
+ number: '{"number":{"format":"number"}}',
28
+ select: '{"select":{"options":[{"name":"Option"}]}}',
29
+ multi_select: '{"multi_select":{"options":[{"name":"Option"}]}}',
30
+ status: '{"status":{}}',
31
+ date: '{"date":{}}',
32
+ checkbox: '{"checkbox":{}}',
33
+ url: '{"url":{}}',
34
+ email: '{"email":{}}',
35
+ phone_number: '{"phone_number":{}}',
36
+ relation: '{"relation":{"database_id":"db-id"}}',
37
+ people: '{"people":{}}',
38
+ files: '{"files":{}}',
39
+ formula: '{"formula":{"expression":"prop(\\"Name\\")"}}',
40
+ };
41
+ // Block examples (for append-block-children, update-block)
42
+ export const BlockExamples = {
43
+ paragraph: '{"paragraph":{"rich_text":[{"text":{"content":"Text"}}]}}',
44
+ heading_1: '{"heading_1":{"rich_text":[{"text":{"content":"Heading"}}]}}',
45
+ heading_2: '{"heading_2":{"rich_text":[{"text":{"content":"Heading"}}]}}',
46
+ heading_3: '{"heading_3":{"rich_text":[{"text":{"content":"Heading"}}]}}',
47
+ bulleted_list_item: '{"bulleted_list_item":{"rich_text":[{"text":{"content":"Item"}}]}}',
48
+ numbered_list_item: '{"numbered_list_item":{"rich_text":[{"text":{"content":"Item"}}]}}',
49
+ to_do: '{"to_do":{"rich_text":[{"text":{"content":"Task"}}],"checked":false}}',
50
+ code: '{"code":{"rich_text":[{"text":{"content":"code"}}],"language":"javascript"}}',
51
+ quote: '{"quote":{"rich_text":[{"text":{"content":"Quote"}}]}}',
52
+ divider: '{"divider":{}}',
53
+ };
54
+ // RichText array example (for create-comment, update-database title/description)
55
+ export const RichTextArrayExample = '[{"text":{"content":"Text"}}]';
56
+ // Filter examples (for query-data-source, search)
57
+ export const FilterExamples = {
58
+ select: '{"property":"Status","select":{"equals":"Done"}}',
59
+ text: '{"property":"Name","rich_text":{"contains":"keyword"}}',
60
+ checkbox: '{"property":"Done","checkbox":{"equals":true}}',
61
+ date: '{"property":"Date","date":{"on_or_after":"2024-01-01"}}',
62
+ and: '{"and":[{"property":"Status","select":{"equals":"Done"}},{"property":"Date","date":{"on_or_after":"2024-01-01"}}]}',
63
+ or: '{"or":[{"property":"Status","select":{"equals":"Done"}},{"property":"Status","select":{"equals":"In Progress"}}]}',
64
+ };
65
+ // Sort examples (for query-data-source)
66
+ export const SortExamples = '[{"property":"Date","direction":"descending"}]';
67
+ // Get examples by type
68
+ export function getExamplesByType(type) {
69
+ switch (type) {
70
+ case 'page':
71
+ return formatExamples('Page property format', PagePropertyExamples);
72
+ case 'schema':
73
+ return formatExamples('Schema property format', SchemaPropertyExamples);
74
+ case 'block':
75
+ return formatExamples('Block format', BlockExamples);
76
+ case 'richTextArray':
77
+ return `RichText array format:\n ${RichTextArrayExample}`;
78
+ case 'filter':
79
+ return `${formatExamples('Filter format', FilterExamples)}\n\nSort format:\n ${SortExamples}`;
80
+ }
81
+ }
82
+ function formatExamples(title, examples) {
83
+ const lines = Object.entries(examples)
84
+ .map(([key, value]) => ` ${key}: ${value}`)
85
+ .join('\n');
86
+ return `${title} examples:\n${lines}`;
87
+ }
@@ -0,0 +1,146 @@
1
+ /**
2
+ * InputSchema field descriptions for MCP tools.
3
+ * Key names match inputSchema property names for type safety.
4
+ */
5
+ /**
6
+ * Field description.
7
+ * desc can be a string or an object with variants: { default: '...', emoji: '...' }
8
+ */
9
+ export interface FieldDesc {
10
+ desc: string | {
11
+ default: string;
12
+ [variant: string]: string;
13
+ };
14
+ }
15
+ /**
16
+ * Field descriptions for all MCP tool input schemas.
17
+ * Key names match the inputSchema property names.
18
+ */
19
+ export declare const Fields: {
20
+ readonly page_id: {
21
+ readonly desc: {
22
+ readonly default: "Page ID";
23
+ readonly target: "Target parent page ID";
24
+ };
25
+ };
26
+ readonly block_id: {
27
+ readonly desc: "Block or page ID";
28
+ };
29
+ readonly database_id: {
30
+ readonly desc: "Database ID";
31
+ };
32
+ readonly data_source_id: {
33
+ readonly desc: {
34
+ readonly default: "Data source ID";
35
+ readonly target: "Target data source ID";
36
+ };
37
+ };
38
+ readonly parent_page_id: {
39
+ readonly desc: "Parent page ID";
40
+ };
41
+ readonly user_id: {
42
+ readonly desc: "User ID";
43
+ };
44
+ readonly property_id: {
45
+ readonly desc: "Property ID (from page properties)";
46
+ };
47
+ readonly discussion_id: {
48
+ readonly desc: "Discussion ID (for replies)";
49
+ };
50
+ readonly start_cursor: {
51
+ readonly desc: "Pagination cursor from previous response";
52
+ };
53
+ readonly page_size: {
54
+ readonly desc: "Number of results (1-100)";
55
+ };
56
+ readonly format: {
57
+ readonly desc: "Output format: 'simple' or 'json'";
58
+ };
59
+ readonly properties: {
60
+ readonly desc: {
61
+ readonly default: "Properties object";
62
+ readonly schema: "Property schema (must include one title property)";
63
+ readonly update: "Properties to add/update/delete (set to null to delete)";
64
+ };
65
+ };
66
+ readonly include_content: {
67
+ readonly desc: "Include page content as markdown (default: true)";
68
+ };
69
+ readonly content: {
70
+ readonly desc: "Content in Markdown";
71
+ };
72
+ readonly archived: {
73
+ readonly desc: "Archive status";
74
+ };
75
+ readonly is_locked: {
76
+ readonly desc: "Lock to prevent UI edits";
77
+ };
78
+ readonly title: {
79
+ readonly desc: "Title";
80
+ };
81
+ readonly description: {
82
+ readonly desc: "Description";
83
+ };
84
+ readonly is_inline: {
85
+ readonly desc: "Inline database";
86
+ };
87
+ readonly filter: {
88
+ readonly desc: {
89
+ readonly default: "Filter object. Example: {\"property\":\"Status\",\"select\":{\"equals\":\"Done\"}}";
90
+ readonly search: "Filter to limit results to pages or data sources. Example: { \"value\": \"page\", \"property\": \"object\" }";
91
+ };
92
+ };
93
+ readonly sorts: {
94
+ readonly desc: "Sort array. Example: [{\"property\":\"Date\",\"direction\":\"descending\"}]";
95
+ };
96
+ readonly children: {
97
+ readonly desc: "Block objects array";
98
+ };
99
+ readonly after: {
100
+ readonly desc: "Insert after this block ID";
101
+ };
102
+ readonly block: {
103
+ readonly desc: "Block data with type-specific properties";
104
+ };
105
+ readonly fetch_nested: {
106
+ readonly desc: "Fetch nested children recursively (WARNING: many API calls)";
107
+ };
108
+ readonly icon: {
109
+ readonly desc: {
110
+ readonly default: "Icon { type: \"emoji\", emoji: \"📝\" } or { type: \"external\", external: { url: \"...\" } }";
111
+ readonly emoji: "Emoji character (e.g. \"📝\", \"🐛\", \"✅\"). Must be an actual emoji, not a name.";
112
+ };
113
+ };
114
+ readonly cover: {
115
+ readonly desc: "Cover image { type: \"external\", external: { url: \"...\" } }";
116
+ };
117
+ readonly rich_text: {
118
+ readonly desc: "Rich text array";
119
+ };
120
+ readonly query: {
121
+ readonly desc: "Search query text";
122
+ };
123
+ readonly sort: {
124
+ readonly desc: "Sort order. Example: { \"direction\": \"descending\", \"timestamp\": \"last_edited_time\" }";
125
+ };
126
+ readonly parent: {
127
+ readonly desc: "Parent (provide either page_id or data_source_id)";
128
+ };
129
+ };
130
+ /**
131
+ * Shorthand accessor for field descriptions.
132
+ * Usage: z.string().describe(F.page_id)
133
+ *
134
+ * For fields with variants (desc is an object):
135
+ * - F.icon → default description
136
+ * - F.icon_emoji → emoji variant description
137
+ */
138
+ export declare const F: { [K in keyof typeof Fields]: string; } & {
139
+ page_id_target: string;
140
+ data_source_id_target: string;
141
+ properties_schema: string;
142
+ properties_update: string;
143
+ filter_search: string;
144
+ icon_emoji: string;
145
+ };
146
+ //# sourceMappingURL=fields.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../../../src/schemas/descriptions/fields.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;CAC9D;AAED;;;GAGG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmK2B,CAAA;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,CAAC,EAgBN,GAAG,CAAC,IAAI,MAAM,OAAO,MAAM,GAAG,MAAM,GAAE,GAAG;IAE/C,cAAc,EAAE,MAAM,CAAA;IACtB,qBAAqB,EAAE,MAAM,CAAA;IAC7B,iBAAiB,EAAE,MAAM,CAAA;IACzB,iBAAiB,EAAE,MAAM,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA"}
@@ -0,0 +1,184 @@
1
+ /**
2
+ * InputSchema field descriptions for MCP tools.
3
+ * Key names match inputSchema property names for type safety.
4
+ */
5
+ /**
6
+ * Field descriptions for all MCP tool input schemas.
7
+ * Key names match the inputSchema property names.
8
+ */
9
+ export const Fields = {
10
+ // ============================================
11
+ // ID Fields
12
+ // ============================================
13
+ page_id: {
14
+ desc: {
15
+ default: 'Page ID',
16
+ target: 'Target parent page ID',
17
+ },
18
+ },
19
+ block_id: {
20
+ desc: 'Block or page ID',
21
+ },
22
+ database_id: {
23
+ desc: 'Database ID',
24
+ },
25
+ data_source_id: {
26
+ desc: {
27
+ default: 'Data source ID',
28
+ target: 'Target data source ID',
29
+ },
30
+ },
31
+ parent_page_id: {
32
+ desc: 'Parent page ID',
33
+ },
34
+ user_id: {
35
+ desc: 'User ID',
36
+ },
37
+ property_id: {
38
+ desc: 'Property ID (from page properties)',
39
+ },
40
+ discussion_id: {
41
+ desc: 'Discussion ID (for replies)',
42
+ },
43
+ // ============================================
44
+ // Pagination
45
+ // ============================================
46
+ start_cursor: {
47
+ desc: 'Pagination cursor from previous response',
48
+ },
49
+ page_size: {
50
+ desc: 'Number of results (1-100)',
51
+ },
52
+ // ============================================
53
+ // Format
54
+ // ============================================
55
+ format: {
56
+ desc: "Output format: 'simple' or 'json'",
57
+ },
58
+ // ============================================
59
+ // Properties
60
+ // ============================================
61
+ properties: {
62
+ desc: {
63
+ default: 'Properties object',
64
+ schema: 'Property schema (must include one title property)',
65
+ update: 'Properties to add/update/delete (set to null to delete)',
66
+ },
67
+ },
68
+ // ============================================
69
+ // Content
70
+ // ============================================
71
+ include_content: {
72
+ desc: 'Include page content as markdown (default: true)',
73
+ },
74
+ content: {
75
+ desc: 'Content in Markdown',
76
+ },
77
+ // ============================================
78
+ // Archive / Lock
79
+ // ============================================
80
+ archived: {
81
+ desc: 'Archive status',
82
+ },
83
+ is_locked: {
84
+ desc: 'Lock to prevent UI edits',
85
+ },
86
+ // ============================================
87
+ // Database Schema
88
+ // ============================================
89
+ title: {
90
+ desc: 'Title',
91
+ },
92
+ description: {
93
+ desc: 'Description',
94
+ },
95
+ is_inline: {
96
+ desc: 'Inline database',
97
+ },
98
+ // ============================================
99
+ // Query
100
+ // ============================================
101
+ filter: {
102
+ desc: {
103
+ default: 'Filter object. Example: {"property":"Status","select":{"equals":"Done"}}',
104
+ search: 'Filter to limit results to pages or data sources. Example: { "value": "page", "property": "object" }',
105
+ },
106
+ },
107
+ sorts: {
108
+ desc: 'Sort array. Example: [{"property":"Date","direction":"descending"}]',
109
+ },
110
+ // ============================================
111
+ // Blocks
112
+ // ============================================
113
+ children: {
114
+ desc: 'Block objects array',
115
+ },
116
+ after: {
117
+ desc: 'Insert after this block ID',
118
+ },
119
+ block: {
120
+ desc: 'Block data with type-specific properties',
121
+ },
122
+ fetch_nested: {
123
+ desc: 'Fetch nested children recursively (WARNING: many API calls)',
124
+ },
125
+ // ============================================
126
+ // Icon & Cover
127
+ // ============================================
128
+ icon: {
129
+ desc: {
130
+ default: 'Icon { type: "emoji", emoji: "📝" } or { type: "external", external: { url: "..." } }',
131
+ emoji: 'Emoji character (e.g. "📝", "🐛", "✅"). Must be an actual emoji, not a name.',
132
+ },
133
+ },
134
+ cover: {
135
+ desc: 'Cover image { type: "external", external: { url: "..." } }',
136
+ },
137
+ // ============================================
138
+ // Rich Text
139
+ // ============================================
140
+ rich_text: {
141
+ desc: 'Rich text array',
142
+ },
143
+ // ============================================
144
+ // Search
145
+ // ============================================
146
+ query: {
147
+ desc: 'Search query text',
148
+ },
149
+ sort: {
150
+ desc: 'Sort order. Example: { "direction": "descending", "timestamp": "last_edited_time" }',
151
+ },
152
+ // ============================================
153
+ // Parent
154
+ // ============================================
155
+ parent: {
156
+ desc: 'Parent (provide either page_id or data_source_id)',
157
+ },
158
+ };
159
+ /**
160
+ * Shorthand accessor for field descriptions.
161
+ * Usage: z.string().describe(F.page_id)
162
+ *
163
+ * For fields with variants (desc is an object):
164
+ * - F.icon → default description
165
+ * - F.icon_emoji → emoji variant description
166
+ */
167
+ export const F = (() => {
168
+ const result = {};
169
+ for (const [key, value] of Object.entries(Fields)) {
170
+ if (typeof value.desc === 'string') {
171
+ result[key] = value.desc;
172
+ }
173
+ else {
174
+ // desc is an object with variants
175
+ result[key] = value.desc.default;
176
+ for (const [variant, desc] of Object.entries(value.desc)) {
177
+ if (variant !== 'default') {
178
+ result[`${key}_${variant}`] = desc;
179
+ }
180
+ }
181
+ }
182
+ }
183
+ return result;
184
+ })();
@@ -0,0 +1,3 @@
1
+ export * from './examples.js';
2
+ export * from './fields.js';
3
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/schemas/descriptions/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA"}
@@ -0,0 +1,2 @@
1
+ export * from './examples.js';
2
+ export * from './fields.js';
@@ -1,6 +1,2 @@
1
- export { AudioBlockSchema, BlockChildrenSchema, BlockSchema, BookmarkBlockSchema, BreadcrumbBlockSchema, BulletedListItemBlockSchema, CalloutBlockSchema, ChildDatabaseBlockSchema, ChildPageBlockSchema, CodeBlockSchema, ColumnBlockSchema, ColumnListBlockSchema, DividerBlockSchema, EmbedBlockSchema, EmojiIconBlockSchema, EquationBlockSchema, ExternalFileSchema, ExternalIconBlockSchema, FileBlockSchema, FileIconBlockSchema, FileObjectSchema, FileUploadSchema, Heading1BlockSchema, Heading2BlockSchema, Heading3BlockSchema, IconBlockSchema, ImageBlockSchema, LinkPreviewBlockSchema, LinkToPageBlockSchema, NotionFileSchema, NumberedListItemBlockSchema, ParagraphBlockSchema, PdfBlockSchema, QuoteBlockSchema, SyncedBlockDuplicateSchema, SyncedBlockOriginalSchema, SyncedBlockSchema, TableBlockSchema, TableOfContentsBlockSchema, TableRowBlockSchema, TemplateBlockSchema, ToDoBlockSchema, ToggleBlockSchema, UnsupportedBlockSchema, VideoBlockSchema, } from './block.js';
2
- export { AnnotationsSchema, ColorSchema, CoverSchema, DatabaseMentionSchema, DatabaseParentSchema, DateMentionSchema, EmojiIconSchema, EquationRichTextSchema, ExternalIconSchema, IconSchema, LinkPreviewMentionSchema, MentionRichTextSchema, MentionSchema, PageMentionSchema, PageParentSchema, ParentSchema, RichTextArraySchema, RichTextSchema, SimpleTextSchema, TemplateMentionDateSchema, TemplateMentionSchema, TemplateMentionUserSchema, TextRichTextSchema, UserMentionSchema, } from './common.js';
3
- export { CheckboxPropertySchemaSchema, CreatedByPropertySchemaSchema, CreatedTimePropertySchemaSchema, DatabasePropertiesSchema, DatabasePropertySchemaSchema, DatabaseTitleSchema, DatePropertySchemaSchema, EmailPropertySchemaSchema, FilesPropertySchemaSchema, FormulaPropertySchemaSchema, LastEditedByPropertySchemaSchema, LastEditedTimePropertySchemaSchema, MultiSelectPropertySchemaSchema, NumberPropertySchemaSchema, PeoplePropertySchemaSchema, PhoneNumberPropertySchemaSchema, RelationPropertySchemaSchema, RichTextPropertySchemaSchema, RollupPropertySchemaSchema, SelectOptionSchema, SelectPropertySchemaSchema, TitlePropertySchemaSchema, UrlPropertySchemaSchema, } from './database.js';
4
- export { FilterSchema, type FilterType, PropertyFilterSchema, SortSchema, SortsSchema, TimestampFilterSchema, } from './filter.js';
5
- export { CheckboxPropertySchema, CreatedByPropertySchema, CreatedTimePropertySchema, DatePropertySchema, EmailPropertySchema, FilesPropertySchema, FormulaPropertySchema, LastEditedByPropertySchema, LastEditedTimePropertySchema, MultiSelectPropertySchema, NumberPropertySchema, PeoplePropertySchema, PhoneNumberPropertySchema, PropertiesSchema, PropertyValueSchema, RelationPropertySchema, RichTextPropertySchema, RollupPropertySchema, SelectPropertySchema, StatusPropertySchema, TitlePropertySchema, UniqueIdPropertySchema, UrlPropertySchema, UserObjectSchema, VerificationPropertySchema, } from './page.js';
1
+ export { F, type FieldDesc, Fields } from './descriptions/index.js';
6
2
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/schemas/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,qBAAqB,EACrB,2BAA2B,EAC3B,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,2BAA2B,EAC3B,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,0BAA0B,EAC1B,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,0BAA0B,EAC1B,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,UAAU,EACV,wBAAwB,EACxB,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,EACzB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,4BAA4B,EAC5B,6BAA6B,EAC7B,+BAA+B,EAC/B,wBAAwB,EACxB,4BAA4B,EAC5B,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,yBAAyB,EACzB,2BAA2B,EAC3B,gCAAgC,EAChC,kCAAkC,EAClC,+BAA+B,EAC/B,0BAA0B,EAC1B,0BAA0B,EAC1B,+BAA+B,EAC/B,4BAA4B,EAC5B,4BAA4B,EAC5B,0BAA0B,EAC1B,kBAAkB,EAClB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,eAAe,CAAA;AAGtB,OAAO,EACL,YAAY,EACZ,KAAK,UAAU,EACf,oBAAoB,EACpB,UAAU,EACV,WAAW,EACX,qBAAqB,GACtB,MAAM,aAAa,CAAA;AAGpB,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,EAC1B,4BAA4B,EAC5B,yBAAyB,EACzB,oBAAoB,EACpB,oBAAoB,EACpB,yBAAyB,EACzB,gBAAgB,EAChB,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,0BAA0B,GAC3B,MAAM,WAAW,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/schemas/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,KAAK,SAAS,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA"}