memos-mcp 1.0.0

package/.vscode/settings.json

@@ -0,0 +1,19 @@
+{
+  "[typescript]": {
+    "editor.formatOnSave": true,
+    "editor.formatOnSaveMode": "file"
+  },
+  "editor.formatOnSave": true,
+  "editor.formatOnSaveMode": "file",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.biome": "explicit",
+    "source.organizeImports.biome": "explicit"
+  },
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "nodejs-testing.extensions": [
+    {
+      "extensions": ["mjs", "cjs", "js", "ts"],
+      "parameters": []
+    }
+  ]
+}

package/AGENTS.md

@@ -0,0 +1,96 @@
+# Agent Guidelines for memos-mcp
+
+## Overview
+
+This is an MCP (Model Context Protocol) server for Memos - a lightweight, self-hosted memo hub. The server provides tools to create and search memos via the Memos API.
+
+## Required Checks Before Committing
+
+**IMPORTANT:** Always run these commands before committing changes:
+
+```bash
+# 1. Type checking - REQUIRED
+npm run typecheck
+
+# 2. Linting - REQUIRED
+npm run lint
+
+# 3. Format check - REQUIRED
+npm run format:check
+
+# 4. Tests - REQUIRED
+npm run test
+```
+
+All checks must pass before committing. You can auto-fix lint and format issues:
+
+```bash
+npm run lint:fix    # Auto-fix lint issues
+npm run format      # Auto-format code
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts              # MCP server entry point
+├── memos-client.ts       # Memos API client
+├── memos-client.test.ts  # Client tests
+├── cert-manager.ts       # SSL certificate auto-fetch & cache
+└── cert-manager.test.ts  # Cert manager tests
+```
+
+## Key Technical Details
+
+### SSL Certificate Handling
+
+The project includes automatic SSL certificate management for servers with incomplete certificate chains (missing intermediates). See `cert-manager.ts`:
+
+- Auto-fetches Let's Encrypt intermediate certificates via HTTPS
+- Caches certificates in `~/.cache/memos-mcp/certs/`
+- Auto-refreshes when cache > 30 days or cert expires within 30 days
+
+### Dependencies
+
+- `@modelcontextprotocol/sdk` - MCP SDK for server implementation
+- `undici` - HTTP client with custom TLS agent support
+
+### Node.js Version
+
+Requires Node.js >= 22.0.0
+
+## Code Style
+
+- Uses Prettier for formatting (config in package.json)
+- Uses ESLint with TypeScript plugin
+- Double quotes for strings
+- Semicolons required
+- 120 character line width
+
+## Testing
+
+Tests use Node.js built-in test runner (`node:test`):
+
+```bash
+npm run test
+```
+
+Integration tests in `cert-manager.test.ts` make real network requests to Let's Encrypt servers.
+
+## Common Tasks
+
+### Adding a new MCP tool
+
+1. Add tool definition in `src/index.ts` under `server.setRequestHandler(ListToolsRequestSchema, ...)`
+2. Add tool handler in `server.setRequestHandler(CallToolRequestSchema, ...)`
+3. Implement the method in `src/memos-client.ts`
+4. Add tests in `src/memos-client.test.ts`
+
+### Updating certificates
+
+Certificates are auto-fetched, but you can force refresh:
+
+```typescript
+import { refreshAllCerts } from "./cert-manager.ts";
+await refreshAllCerts();
+```

package/Jenkinsfile

@@ -0,0 +1,80 @@
+pipeline {
+  agent any
+  tools {
+    nodejs 'NodeJS 24.x'
+  }
+  stages {
+    stage('Checkout') {
+      steps {
+        checkout scm
+      }
+    }
+
+    stage('Install') {
+      steps {
+        script {
+          sh 'npm i'
+        }
+      }
+    }
+
+    stage('Lint') {
+      steps {
+        script {
+          sh 'npm run lint --if-present'
+          sh 'npm run format:check --if-present'
+        }
+      }
+    }
+
+    stage('Test') {
+      steps {
+        script {
+          sh 'npm test --if-present'
+        }
+      }
+    }
+
+    stage('Build') {
+      steps {
+        script {
+          sh 'npm run build --if-present'
+        }
+      }
+    }
+
+    stage('Publish Official Release') {
+      when {
+        expression { env.TAG_NAME != null } // Only run for tag builds
+      }
+      environment {
+          NPM_TOKEN = credentials('npm-verdaccio-publish-token')
+      }
+      steps {
+          sh 'npm config set //verdaccio-verdaccio-68mj54-e6081a-192-168-111-123.traefik.me/:_authToken=${NPM_TOKEN} --location project'
+          sh 'npm publish --tag latest'
+      }
+    }
+
+    // stage('Publish Snapshot Build') {
+    //   when {
+    //     expression { env.TAG_NAME == null } // Only run for non-tag builds
+    //   }
+    //   environment {
+    //       NPM_TOKEN = credentials('npm-verdaccio-publish-token')
+    //   }
+    //   steps {
+    //       sh 'npm config set //verdaccio-verdaccio-68mj54-e6081a-192-168-111-123.traefik.me/:_authToken=${NPM_TOKEN} --location project'
+    //       sh 'npm version 0.0.0-BUILD-${BUILD_NUMBER} --no-git-tag-version' // Apply snapshot version
+    //       sh 'npm publish --tag snapshot' // Publish with snapshot tag
+    //   }
+    // }
+
+  }
+
+  post {
+    always {
+      cleanWs()
+    }
+  }
+}

package/README.md

@@ -0,0 +1,164 @@
+# Memos MCP Server
+
+A Model Context Protocol (MCP) server for [Memos](https://usememos.com/) - a self-hosted memo hub. This server enables AI assistants to create and search memos through the Memos API.
+
+## Features
+
+- **Create memos** with content, visibility settings, and location data
+- **Search memos** by text query, tag, visibility, or state
+- **Get individual memos** by ID
+
+## Requirements
+
+- Node.js 22+ (uses native TypeScript type stripping)
+- A running Memos instance
+- Personal Access Token from your Memos account
+
+## Installation
+
+```bash
+npm install
+```
+
+## Configuration
+
+The server requires two environment variables:
+
+| Variable             | Description                      | Example                     |
+| -------------------- | -------------------------------- | --------------------------- |
+| `MEMOS_URL`          | Your Memos instance URL          | `https://memos.example.com` |
+| `MEMOS_ACCESS_TOKEN` | Personal Access Token from Memos | `eyJhbGciOiJIUzI1...`       |
+
+### Getting an Access Token
+
+1. Log into your Memos instance
+2. Go to Settings → My Account
+3. Create a new Personal Access Token
+4. Copy the token (it's only shown once)
+
+## Usage
+
+### Running the Server
+
+```bash
+MEMOS_URL=https://memos.example.com MEMOS_ACCESS_TOKEN=your-token npm start
+```
+
+### OpenCode Configuration
+
+Add to your `opencode.json` (or `opencode.jsonc`):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "memos": {
+      "type": "local",
+      "command": ["node", "/path/to/memos-map/src/index.ts"],
+      "enabled": true,
+      "environment": {
+        "MEMOS_URL": "https://your-memos-instance.com",
+        "MEMOS_ACCESS_TOKEN": "{env:MEMOS_ACCESS_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+You can also use environment variables directly:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "memos": {
+      "type": "local",
+      "command": ["node", "/path/to/memos-map/src/index.ts"],
+      "enabled": true,
+      "environment": {
+        "MEMOS_URL": "{env:MEMOS_URL}",
+        "MEMOS_ACCESS_TOKEN": "{env:MEMOS_ACCESS_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+Then use `memos` tools in your prompts:
+
+```
+Create a memo with today's meeting notes. use memos
+```
+
+### Claude Desktop Configuration
+
+Add to your Claude Desktop MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "memos": {
+      "command": "node",
+      "args": ["/path/to/memos-map/src/index.ts"],
+      "env": {
+        "MEMOS_URL": "https://your-memos-instance.com",
+        "MEMOS_ACCESS_TOKEN": "your-access-token-here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `create_memo`
+
+Create a new memo.
+
+| Parameter    | Type   | Required | Description                                              |
+| ------------ | ------ | -------- | -------------------------------------------------------- |
+| `content`    | string | Yes      | Memo content (supports Markdown)                         |
+| `visibility` | string | No       | `PRIVATE`, `PROTECTED`, or `PUBLIC` (default: `PRIVATE`) |
+| `location`   | object | No       | Location with `placeholder`, `latitude`, `longitude`     |
+
+### `search_memos`
+
+Search and list memos.
+
+| Parameter    | Type   | Required | Description                                |
+| ------------ | ------ | -------- | ------------------------------------------ |
+| `query`      | string | No       | Text to search in memo content             |
+| `tag`        | string | No       | Filter by tag (without #)                  |
+| `visibility` | string | No       | Filter by visibility                       |
+| `state`      | string | No       | `NORMAL` or `ARCHIVED` (default: `NORMAL`) |
+| `pageSize`   | number | No       | Results per page (default: 20)             |
+| `orderBy`    | string | No       | Sort order (default: `display_time desc`)  |
+
+### `get_memo`
+
+Get a single memo by ID.
+
+| Parameter | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| `memoId`  | string | Yes      | The memo ID |
+
+## Development
+
+### Running Tests
+
+```bash
+npm test
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts              # MCP server entry point
+├── memos-client.ts       # Memos API client
+└── memos-client.test.ts  # Tests
+```
+
+## License
+
+MIT

package/RELEASE.md

@@ -0,0 +1,25 @@
+## Release Process
+
+This project uses a two-pronged release approach:
+
+### Official Releases (Versioned)
+
+Official releases follow Semantic Versioning (MAJOR.MINOR.PATCH) and are published to npm with the `latest` tag.
+
+**Steps for a Developer to Create an Official Release:**
+
+1.  **Ensure your local `main` branch is up-to-date** and all changes intended for the release are merged.
+2.  **Run `npm version <patch|minor|major>` locally.** This command will:
+    - Increment the version in `package.json`.
+    - Create a git commit for the version change.
+    - Create a corresponding local git tag (e.g., `v1.0.0`).
+    - Example: `npm version patch`
+3.  **Push the commit and the new tag to the remote repository:**
+    ```bash
+    git push && git push --tags
+    ```
+4.  **Jenkins will automatically detect the new tag** and trigger a pipeline build. The `Publish Official Release` stage in the `Jenkinsfile` will then publish the package to npm with the `latest` tag.
+
+### Snapshot Builds
+
+For builds on branches that are not triggered by a git tag (e.g., `main` branch builds from regular commits), a snapshot version is automatically applied and published to npm with a `snapshot` tag. These builds are primarily for continuous integration and testing purposes and do not represent official releases.

package/eslint.config.js

@@ -0,0 +1,34 @@
+// eslint.config.js
+import js from "@eslint/js";
+import typescript from "@typescript-eslint/eslint-plugin";
+import typescriptParser from "@typescript-eslint/parser";
+import prettier from "eslint-plugin-prettier";
+import prettierConfig from "eslint-config-prettier";
+import globals from "globals";
+
+export default [
+  js.configs.recommended,
+  {
+    files: ["**/*.{js,mjs,cjs,ts,tsx}"],
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      parser: typescriptParser,
+      globals: {
+        ...globals.node,
+        RequestInit: "readonly",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": typescript,
+      prettier: prettier,
+    },
+    rules: {
+      ...typescript.configs.recommended.rules,
+      ...prettierConfig.rules,
+      "prettier/prettier": "error",
+      "no-unused-vars": "off",
+      "@typescript-eslint/no-unused-vars": "error",
+    },
+  },
+];

package/memory.md

@@ -0,0 +1,51 @@
+# Memory
+
+## Project Purpose
+
+This project appears to be a TypeScript project template, providing a basic setup for developing and testing TypeScript code. It includes a simple `add` function and a corresponding unit test.
+
+## Project Structure
+
+- `.gitignore`: Specifies intentionally untracked files to ignore.
+- `eslint.config.js`: ESLint configuration for linting TypeScript files.
+- `Jenkinsfile`: Likely a Jenkins pipeline definition for CI/CD.
+- `package-lock.json`: Records the exact dependency tree.
+- `package.json`: Project metadata, scripts, and dependencies.
+- `README.md`: Project README file.
+- `RELEASE.md`: Release notes or guidelines.
+- `src/`: Source code directory.
+  - `src/index.ts`: Contains the main application logic (currently a simple `add` function).
+- `test/`: Test code directory.
+  - `test/index.test.ts`: Contains unit tests for `src/index.ts`.
+
+## Project Technical Details
+
+### Technical Stack
+
+- **Language**: Node.js Native TypeScript (means not compiler required and must import module with `.ts`/`.js` suffix)
+- **Runtime**: Node.js
+- **Linting**: ESLint with `@typescript-eslint/eslint-plugin` and `@typescript-eslint/parser`
+- **Formatting**: Prettier with `eslint-config-prettier` and `eslint-plugin-prettier`
+- **Testing**: Node.js built-in test runner (`node --test`)
+
+### Important Dependent Libraries
+
+- `@types/node`: Type definitions for Node.js.
+- `@typescript-eslint/eslint-plugin`: ESLint plugin for TypeScript.
+- `@typescript-eslint/parser`: Parser for ESLint to understand TypeScript.
+- `eslint`: Linter.
+- `eslint-config-prettier`: Disables ESLint rules that conflict with Prettier.
+- `eslint-plugin-prettier`: Runs Prettier as an ESLint rule.
+- `prettier`: Code formatter.
+
+## Features Implemented
+
+- A basic `add` function in `src/index.ts`.
+- A unit test for the `add` function in `test/index.test.ts`.
+- Linting and formatting configurations.
+- A test script using Node.js's built-in test runner.
+
+## Design Patterns
+
+- **Modular Design**: The `add` function is exported from `index.ts` and imported into `index.test.ts`, demonstrating modularity.
+- **Unit Testing**: The project includes a dedicated test file and uses a unit testing framework to verify the correctness of the `add` function.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "memos-mcp",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "MCP server for Memos - create and search memos",
+  "main": "src/index.ts",
+  "bin": {
+    "memos-mcp": "./src/index.ts"
+  },
+  "scripts": {
+    "start": "node src/index.ts",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "undici": "^7.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@typescript-eslint/eslint-plugin": "^8.48.1",
+    "@typescript-eslint/parser": "^8.48.1",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "prettier": "^3.7.4"
+  },
+  "prettier": {
+    "semi": true,
+    "singleQuote": false,
+    "printWidth": 120,
+    "tabWidth": 2,
+    "trailingComma": "all",
+    "endOfLine": "lf"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}