get_notebook_mcp_server 1.0.1

package/README.md

@@ -0,0 +1,81 @@
+# Get Notes MCP Server
+
+A Model Context Protocol (MCP) server for integrating with Get Notes API. This server provides tools to search and recall knowledge from your Get Notes knowledge base.
+
+## Features
+
+- **Knowledge Search**: AI-processed search that returns synthesized answers and references.
+- **Knowledge Recall**: Raw recall of relevant notes and files.
+- **Rate Limiting**: Built-in protection with QPS < 2 and Total Requests < 5000 limits.
+- **Retry Mechanism**: Automatic retries for transient network errors (5xx).
+
+## Installation
+
+1. Clone the repository
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+3. Create `.env` file from example:
+   ```bash
+   cp .env.example .env
+   ```
+4. Configure your API key in `.env`:
+   ```
+   GET_API_KEY=your_api_key_here
+   ```
+
+## Usage
+
+### Running the Server
+
+```bash
+node index.js
+```
+
+### Testing with MCP Inspector
+
+You can test the MCP server interactively using the MCP Inspector:
+
+```bash
+npx @modelcontextprotocol/inspector node index.js
+```
+
+### Tools
+
+#### `search_knowledge`
+Search the knowledge base with AI processing.
+
+**Parameters:**
+- `question` (string, required): The question to ask.
+- `topic_ids` (array<string>, required): List of knowledge base IDs.
+- `deep_seek` (boolean): Enable deep thinking mode (default: true).
+- `history` (array): Chat history for context.
+
+#### `recall_knowledge`
+Raw recall from knowledge base without AI synthesis.
+
+**Parameters:**
+- `question` (string, required): The question or query.
+- `topic_id` (string, required): Knowledge base ID.
+- `top_k` (number): Number of results to return (default: 10).
+- `intent_rewrite` (boolean): Enable intent rewrite (default: false).
+
+## Development
+
+### Running Tests
+
+```bash
+npm test
+```
+
+### Project Structure
+
+- `src/api`: API client implementation
+- `src/utils`: Utility classes (RateLimiter, etc.)
+- `tests`: Unit and integration tests
+- `index.js`: Main MCP server entry point
+
+## License
+
+ISC

package/index.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+    CallToolRequestSchema,
+    ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import dotenv from 'dotenv';
+import { ApiClient } from './src/api/client.js';
+import logger from './src/logger.js';
+
+dotenv.config();
+
+const API_KEY = process.env.GET_API_KEY;
+if (!API_KEY) {
+    logger.error('GET_API_KEY environment variable is required');
+    process.exit(1);
+}
+
+const apiClient = new ApiClient({ apiKey: API_KEY });
+
+const server = new Server(
+    {
+        name: 'get-notes-mcp',
+        version: '1.0.0',
+    },
+    {
+        capabilities: {
+            tools: {},
+        },
+    }
+);
+
+/**
+ * Tool Definitions
+ */
+const SEARCH_KNOWLEDGE_TOOL = {
+    name: 'search_knowledge',
+    description: 'Search knowledge base with AI processing. Returns synthesized answers and references.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            question: {
+                type: 'string',
+                description: 'The question to ask'
+            },
+            topic_ids: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'List of knowledge base IDs (currently supports only 1)'
+            },
+            deep_seek: {
+                type: 'boolean',
+                description: 'Enable deep thinking mode',
+                default: true
+            },
+            history: {
+                type: 'array',
+                description: 'Chat history for context',
+                items: {
+                    type: 'object',
+                    properties: {
+                        content: { type: 'string' },
+                        role: { type: 'string', enum: ['user', 'assistant'] }
+                    }
+                }
+            }
+        },
+        required: ['question', 'topic_ids']
+    }
+};
+
+const RECALL_KNOWLEDGE_TOOL = {
+    name: 'recall_knowledge',
+    description: 'Raw recall from knowledge base without AI synthesis. Returns list of relevant notes/files.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            question: {
+                type: 'string',
+                description: 'The question or query'
+            },
+            topic_id: {
+                type: 'string',
+                description: 'Knowledge base ID'
+            },
+            top_k: {
+                type: 'number',
+                description: 'Number of results to return',
+                default: 10
+            },
+            intent_rewrite: {
+                type: 'boolean',
+                description: 'Enable intent rewrite',
+                default: false
+            }
+        },
+        required: ['question', 'topic_id']
+    }
+};
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [SEARCH_KNOWLEDGE_TOOL, RECALL_KNOWLEDGE_TOOL],
+    };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        const { name, arguments: args } = request.params;
+
+        switch (name) {
+            case 'search_knowledge': {
+                const params = args;
+                // Ensure topic_ids is array
+                if (!Array.isArray(params.topic_ids)) {
+                    throw new Error('topic_ids must be an array');
+                }
+
+                const response = await apiClient.searchKnowledge(params);
+                // Handle stream or json response. For MCP tool, we typically wait for full response or handle stream if supported.
+                // The API guide says /stream is optional path, but client uses post /knowledge/search.
+                // If it returns stream, we might need to buffer it or use the non-stream version.
+                // For simplicity in this version, we assume non-stream JSON response unless stream param is explicitly handled.
+                // Actually the API guide shows stream response format. Let's assume we want the final answer.
+                // If the API returns a stream, axios might return a stream object.
+
+                // For now, let's assume standard JSON response if stream is not set to true in params.
+                // If the user wants stream, we might need a different approach, but MCP tools usually return text.
+
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(response.data, null, 2),
+                        },
+                    ],
+                };
+            }
+
+            case 'recall_knowledge': {
+                const params = args;
+                const response = await apiClient.recallKnowledge(params);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(response.data, null, 2),
+                        },
+                    ],
+                };
+            }
+
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    } catch (error) {
+        logger.error('Tool execution error', { error: error.message });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+
+async function runServer() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info('Get Notes MCP Server running on stdio');
+}
+
+runServer().catch((error) => {
+    logger.error('Fatal error running server', { error });
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "get_notebook_mcp_server",
+  "version": "1.0.1",
+  "description": "MCP server for Get Notes API integration",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "get-notes-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "get-notes",
+    "ai"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.22.0",
+    "axios": "^1.13.2",
+    "dotenv": "^17.2.3",
+    "winston": "^3.18.3",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0"
+  }
+}

package/src/api/client.js

@@ -0,0 +1,91 @@
+import axios from 'axios';
+import { globalRateLimiter } from '../utils/rateLimiter.js';
+import logger from '../logger.js';
+
+export class ApiClient {
+    constructor(config) {
+        this.baseUrl = config.baseUrl || 'https://open-api.biji.com/getnote/openapi';
+        this.apiKey = config.apiKey;
+
+        if (!this.apiKey) {
+            throw new Error('API Key is required');
+        }
+
+        this.client = axios.create({
+            baseURL: this.baseUrl,
+            headers: {
+                'Content-Type': 'application/json',
+                'Connection': 'keep-alive',
+                'Authorization': `Bearer ${this.apiKey}`,
+                'X-OAuth-Version': '1'
+            }
+        });
+
+        // Add response interceptor for error logging
+        this.client.interceptors.response.use(
+            response => response,
+            error => {
+                logger.error('API Request Failed:', {
+                    url: error.config?.url,
+                    status: error.response?.status,
+                    data: error.response?.data,
+                    message: error.message
+                });
+                return Promise.reject(error);
+            }
+        );
+    }
+
+    /**
+     * Execute a request with rate limiting and retries
+     * @param {Function} requestFn 
+     * @param {number} retries 
+     */
+    async executeRequest(requestFn, retries = 3) {
+        return globalRateLimiter.schedule(async () => {
+            let lastError;
+            for (let i = 0; i < retries; i++) {
+                try {
+                    return await requestFn();
+                } catch (error) {
+                    lastError = error;
+                    const isRetryable = !error.response || (error.response.status >= 500 && error.response.status < 600) || error.code === 'ECONNABORTED';
+
+                    if (!isRetryable || i === retries - 1) {
+                        throw error;
+                    }
+
+                    // Exponential backoff: 1000ms, 2000ms, 4000ms
+                    const delay = 1000 * Math.pow(2, i);
+                    logger.warn(`Request failed, retrying in ${delay}ms... (${i + 1}/${retries})`);
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                }
+            }
+            throw lastError;
+        });
+    }
+
+    /**
+     * Knowledge Search (AI Processed)
+     * @param {Object} params 
+     * @returns {Promise<any>}
+     */
+    async searchKnowledge(params) {
+        return this.executeRequest(() =>
+            this.client.post('/knowledge/search', params, {
+                responseType: params.stream ? 'stream' : 'json'
+            })
+        );
+    }
+
+    /**
+     * Knowledge Recall (Raw)
+     * @param {Object} params 
+     * @returns {Promise<any>}
+     */
+    async recallKnowledge(params) {
+        return this.executeRequest(() =>
+            this.client.post('/knowledge/search/recall', params)
+        );
+    }
+}

package/src/logger.js

@@ -0,0 +1,19 @@
+import winston from 'winston';
+
+const logger = winston.createLogger({
+    level: 'info',
+    format: winston.format.combine(
+        winston.format.timestamp(),
+        winston.format.json()
+    ),
+    transports: [
+        new winston.transports.Console({
+            format: winston.format.combine(
+                winston.format.colorize(),
+                winston.format.simple()
+            )
+        })
+    ]
+});
+
+export default logger;

package/src/utils/rateLimiter.js

@@ -0,0 +1,82 @@
+/**
+ * Rate Limiter implementation
+ * Limits requests to:
+ * - QPS < 2 (Minimum 500ms interval between requests)
+ * - Total requests < 5000
+ */
+export class RateLimiter {
+  constructor(maxQps = 2, maxTotal = 5000) {
+    this.minInterval = 1000 / maxQps; // Minimum interval in ms
+    this.maxTotal = maxTotal;
+    this.requestCount = 0;
+    this.lastRequestTime = 0;
+    this.queue = [];
+    this.processing = false;
+  }
+
+  /**
+   * Execute a function with rate limiting
+   * @param {Function} fn - The async function to execute
+   * @returns {Promise<any>} - The result of the function
+   */
+  async schedule(fn) {
+    if (this.requestCount >= this.maxTotal) {
+      throw new Error(`Total request limit of ${this.maxTotal} exceeded.`);
+    }
+
+    return new Promise((resolve, reject) => {
+      this.queue.push({ fn, resolve, reject });
+      this.processQueue();
+    });
+  }
+
+  async processQueue() {
+    if (this.processing || this.queue.length === 0) {
+      return;
+    }
+
+    this.processing = true;
+
+    while (this.queue.length > 0) {
+      if (this.requestCount >= this.maxTotal) {
+        const { reject } = this.queue.shift();
+        reject(new Error(`Total request limit of ${this.maxTotal} exceeded.`));
+        continue;
+      }
+
+      const now = Date.now();
+      const timeSinceLastRequest = now - this.lastRequestTime;
+      
+      if (timeSinceLastRequest < this.minInterval) {
+        const waitTime = this.minInterval - timeSinceLastRequest;
+        await new Promise(resolve => setTimeout(resolve, waitTime));
+      }
+
+      const { fn, resolve, reject } = this.queue.shift();
+      
+      this.lastRequestTime = Date.now();
+      this.requestCount++;
+
+      try {
+        const result = await fn();
+        resolve(result);
+      } catch (error) {
+        reject(error);
+      }
+    }
+
+    this.processing = false;
+  }
+
+  /**
+   * Get current stats
+   */
+  getStats() {
+    return {
+      requestCount: this.requestCount,
+      queueLength: this.queue.length
+    };
+  }
+}
+
+export const globalRateLimiter = new RateLimiter(2, 5000);