@hasna/knowledge 0.2.1 → 0.2.2

package/.takumi/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(connectors --help)"
+    ]
+  }
+}

package/LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -48,7 +49,7 @@
       "Contribution" shall mean any work of authorship, including
       the original version of the Work and any modifications or additions
       to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
+      submitted to the Licensor for inclusion in the Work by the copyright owner
       or by an individual or Legal Entity authorized to submit on behalf of
       the copyright owner. For the purposes of this definition, "submitted"
       means any form of electronic, verbal, or written communication sent
@@ -60,7 +61,7 @@
       designated in writing by the copyright owner as "Not a Contribution."
 
       "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
+      on behalf of whom a Contribution has been received by the Licensor and
       subsequently incorporated within the Work.
 
    2. Grant of Copyright License. Subject to the terms and conditions of
@@ -106,7 +107,7 @@
       (d) If the Work includes a "NOTICE" text file as part of its
           distribution, then any Derivative Works that You distribute must
           include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
+          within such NOTICE file, excluding any notices that do not
           pertain to any part of the Derivative Works, in at least one
           of the following places: within a NOTICE text file distributed
           as part of the Derivative Works; within the Source form or
@@ -175,18 +176,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 Hasna, Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -199,4 +189,3 @@
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-

package/README.md

@@ -144,3 +144,24 @@ Every command returns structured JSON when `--json` is passed:
 - **Safe deletes**: `--yes` flag required; no accidental deletions
 - **Concurrent-safe**: file locking prevents corruption from parallel agents
 - **Scriptable**: works in pipelines, CI, and any automation tool
+
+## MCP Server
+
+```bash
+open-knowledge-mcp
+```
+
+## HTTP mode
+
+Run a shared Streamable HTTP MCP server (127.0.0.1 only):
+
+```bash
+open-knowledge-mcp --http      # default port 8819
+open-knowledge-mcp --http --port 8819
+MCP_HTTP=1 open-knowledge-mcp
+```
+
+- Health: `GET http://127.0.0.1:8819/health`
+- MCP: `POST http://127.0.0.1:8819/mcp`
+
+Stdio remains the default when no `--http` flag is passed.

package/bin/open-knowledge.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 // @bun
-import{mkdirSync as c,readFileSync as L,writeFileSync as u,existsSync as k,renameSync as f,unlinkSync as b}from"fs";import{dirname as m}from"path";import{homedir as i}from"os";import{randomUUID as P}from"crypto";function v(){return`${i()}/.open-knowledge/db.json`}function x(B){if(!k(B))c(m(B),{recursive:!0}),u(B,JSON.stringify({items:[]},null,2))}function d(B){return`${B}.lock`}function g(B,W){let Q=Date.now();while(Date.now()-Q<5000){try{if(!k(B)){u(B,JSON.stringify({owner:W,ts:Date.now()}));return}let C=JSON.parse(L(B,"utf8"));if(Date.now()-C.ts>1e4)b(B)}catch{}let J=Date.now();while(Date.now()-J<50);}throw Error(`Could not acquire lock on ${B} after 5000ms`)}function l(B,W){try{if(k(B)){if(JSON.parse(L(B,"utf8")).owner===W)b(B)}}catch{}}function G(B){x(B);let W=L(B,"utf8"),z=JSON.parse(W);if(!z||!Array.isArray(z.items))return{items:[]};return z}function M(B,W){let z=`${B}.tmp.${P()}`;u(z,JSON.stringify(W,null,2)),f(z,B)}function O(B,W){let z=P(),K=d(B);g(K,z);try{return W()}finally{l(K,z)}}function p(){return`k_${Date.now().toString(36)}_${Math.random().toString(36).slice(2,8)}`}var A={name:"@hasna/knowledge",version:"0.2.1",description:"Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",type:"module",bin:{"open-knowledge":"./src/cli.ts"},scripts:{test:"bun test","test:cli":"bun test tests/cli.test.ts",build:"bun build --target=bun --outfile=bin/open-knowledge.js --minify src/cli.ts",prepublishOnly:"bun run build",postinstall:"bun run build"},keywords:["knowledge","cli","agents","json","notes","local","store"],license:"Apache-2.0",repository:{type:"git",url:"https://github.com/hasna/knowledge"},bugs:{url:"https://github.com/hasna/knowledge/issues"},author:"Hasna Inc. <hasna@example.com>",engines:{bun:">=1.0",node:">=18"}};var h={debug:0,info:1,warn:2,error:3},s=()=>{if(process.env.DEBUG)return"debug";if(process.env.LOG_LEVEL==="debug")return"debug";if(process.env.LOG_LEVEL==="warn")return"warn";if(process.env.LOG_LEVEL==="error")return"error";return"info"};function D(B,W,z){if(h[B]<h[s()])return;let K={debug:"[DEBUG]",info:"[INFO]",warn:"[WARN]",error:"[ERROR]"}[B],Q=z?`${K} ${W} ${JSON.stringify(z)}`:`${K} ${W}`;if(B==="error")console.error(Q);else console.error(Q)}var e=["add","list","get","delete","update","export","prune","dedupe","stats","help"],n={ls:"list",rm:"delete",edit:"update"};function o(B){let W=[],z={};for(let K=0;K<B.length;K+=1){let Q=B[K];if(!Q.startsWith("-")){W.push(Q);continue}switch(Q){case"--json":z.json=!0;break;case"--yes":case"-y":z.yes=!0;break;case"--help":case"-h":z.help=!0;break;case"--version":case"-v":z.version=!0;break;case"--desc":z.desc=!0;break;case"--page":case"-p":z.page=Number(B[K+1]),K+=1;break;case"--limit":case"-l":z.limit=Number(B[K+1]),K+=1;break;case"--search":case"-s":z.search=B[K+1],K+=1;break;case"--sort":z.sort=B[K+1],K+=1;break;case"--id":z.id=B[K+1],K+=1;break;case"--store":z.store=B[K+1],K+=1;break;case"--title":z.title=B[K+1],K+=1;break;case"--content":z.content=B[K+1],K+=1;break;case"--url":z.url=B[K+1],K+=1;break;case"--tag":case"-t":z.tag=B[K+1],K+=1;break;case"--format":z.format=B[K+1],K+=1;break;case"--completions":z.completions=B[K+1],K+=1;break;case"--no-color":z.noColor=!0;break;case"--scope":z.scope=B[K+1],K+=1;break;case"--older-than":z.olderThan=Number(B[K+1]),K+=1;break;case"--empty":z.empty=!0;break;default:throw Error(`Unknown flag: ${Q}. Run 'open-knowledge --help' for valid options.`)}}return{positional:W,flags:z}}function t(B){if(!B)return"";return n[B]??B}function a(B,W){let z=Array.from({length:B.length+1},()=>Array(W.length+1).fill(0));for(let K=0;K<=B.length;K+=1)z[K][0]=K;for(let K=0;K<=W.length;K+=1)z[0][K]=K;for(let K=1;K<=B.length;K+=1)for(let Q=1;Q<=W.length;Q+=1){let J=B[K-1]===W[Q-1]?0:1;z[K][Q]=Math.min(z[K-1][Q]+1,z[K][Q-1]+1,z[K-1][Q-1]+J)}return z[B.length][W.length]}function z0(B){if(!B)return"";let W=[...e,...Object.keys(n)],z="",K=Number.POSITIVE_INFINITY;for(let Q of W){let J=a(B,Q);if(J<K)K=J,z=Q}return K<=3?z:""}function B0(){console.log(`open-knowledge - local agent knowledge store
+import{mkdirSync as c,readFileSync as L,writeFileSync as u,existsSync as k,renameSync as m,unlinkSync as b}from"fs";import{dirname as f}from"path";import{homedir as i}from"os";import{randomUUID as P}from"crypto";function v(){return`${i()}/.open-knowledge/db.json`}function x(B){if(!k(B))c(f(B),{recursive:!0}),u(B,JSON.stringify({items:[]},null,2))}function d(B){return`${B}.lock`}function g(B,W){let Q=Date.now();while(Date.now()-Q<5000){try{if(!k(B)){u(B,JSON.stringify({owner:W,ts:Date.now()}));return}let C=JSON.parse(L(B,"utf8"));if(Date.now()-C.ts>1e4)b(B)}catch{}let J=Date.now();while(Date.now()-J<50);}throw Error(`Could not acquire lock on ${B} after 5000ms`)}function l(B,W){try{if(k(B)){if(JSON.parse(L(B,"utf8")).owner===W)b(B)}}catch{}}function G(B){x(B);let W=L(B,"utf8"),z=JSON.parse(W);if(!z||!Array.isArray(z.items))return{items:[]};return z}function M(B,W){let z=`${B}.tmp.${P()}`;u(z,JSON.stringify(W,null,2)),m(z,B)}function O(B,W){let z=P(),K=d(B);g(K,z);try{return W()}finally{l(K,z)}}function p(){return`k_${Date.now().toString(36)}_${Math.random().toString(36).slice(2,8)}`}var A={name:"@hasna/knowledge",version:"0.2.2",description:"Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",type:"module",bin:{"open-knowledge":"./src/cli.ts","open-knowledge-mcp":"./src/mcp.js"},scripts:{test:"bun test","test:cli":"bun test tests/cli.test.ts",build:"bun build --target=bun --outfile=bin/open-knowledge.js --minify src/cli.ts",prepublishOnly:"bun run build",postinstall:"bun run build"},keywords:["knowledge","cli","agents","json","notes","local","store"],license:"Apache-2.0",repository:{type:"git",url:"https://github.com/hasna/knowledge"},bugs:{url:"https://github.com/hasna/knowledge/issues"},author:"Hasna Inc. <hasna@example.com>",engines:{bun:">=1.0",node:">=18"},dependencies:{"@modelcontextprotocol/sdk":"^1.29.0",zod:"^4.3.6"}};var h={debug:0,info:1,warn:2,error:3},r=()=>{if(process.env.DEBUG)return"debug";if(process.env.LOG_LEVEL==="debug")return"debug";if(process.env.LOG_LEVEL==="warn")return"warn";if(process.env.LOG_LEVEL==="error")return"error";return"info"};function D(B,W,z){if(h[B]<h[r()])return;let K={debug:"[DEBUG]",info:"[INFO]",warn:"[WARN]",error:"[ERROR]"}[B],Q=z?`${K} ${W} ${JSON.stringify(z)}`:`${K} ${W}`;if(B==="error")console.error(Q);else console.error(Q)}var s=["add","list","get","delete","update","export","prune","dedupe","stats","help"],n={ls:"list",rm:"delete",edit:"update"};function o(B){let W=[],z={};for(let K=0;K<B.length;K+=1){let Q=B[K];if(!Q.startsWith("-")){W.push(Q);continue}switch(Q){case"--json":z.json=!0;break;case"--yes":case"-y":z.yes=!0;break;case"--help":case"-h":z.help=!0;break;case"--version":case"-v":z.version=!0;break;case"--desc":z.desc=!0;break;case"--page":case"-p":z.page=Number(B[K+1]),K+=1;break;case"--limit":case"-l":z.limit=Number(B[K+1]),K+=1;break;case"--search":case"-s":z.search=B[K+1],K+=1;break;case"--sort":z.sort=B[K+1],K+=1;break;case"--id":z.id=B[K+1],K+=1;break;case"--store":z.store=B[K+1],K+=1;break;case"--title":z.title=B[K+1],K+=1;break;case"--content":z.content=B[K+1],K+=1;break;case"--url":z.url=B[K+1],K+=1;break;case"--tag":case"-t":z.tag=B[K+1],K+=1;break;case"--format":z.format=B[K+1],K+=1;break;case"--completions":z.completions=B[K+1],K+=1;break;case"--no-color":z.noColor=!0;break;case"--scope":z.scope=B[K+1],K+=1;break;case"--older-than":z.olderThan=Number(B[K+1]),K+=1;break;case"--empty":z.empty=!0;break;default:throw Error(`Unknown flag: ${Q}. Run 'open-knowledge --help' for valid options.`)}}return{positional:W,flags:z}}function t(B){if(!B)return"";return n[B]??B}function a(B,W){let z=Array.from({length:B.length+1},()=>Array(W.length+1).fill(0));for(let K=0;K<=B.length;K+=1)z[K][0]=K;for(let K=0;K<=W.length;K+=1)z[0][K]=K;for(let K=1;K<=B.length;K+=1)for(let Q=1;Q<=W.length;Q+=1){let J=B[K-1]===W[Q-1]?0:1;z[K][Q]=Math.min(z[K-1][Q]+1,z[K][Q-1]+1,z[K-1][Q-1]+J)}return z[B.length][W.length]}function z0(B){if(!B)return"";let W=[...s,...Object.keys(n)],z="",K=Number.POSITIVE_INFINITY;for(let Q of W){let J=a(B,Q);if(J<K)K=J,z=Q}return K<=3?z:""}function B0(){console.log(`open-knowledge - local agent knowledge store
 
 Usage:
   open-knowledge <command> [options]

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@hasna/knowledge",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   "type": "module",
   "bin": {
-    "open-knowledge": "./src/cli.ts"
+    "open-knowledge": "./src/cli.ts",
+    "open-knowledge-mcp": "./src/mcp.js"
   },
   "scripts": {
     "test": "bun test",
@@ -34,5 +35,9 @@
   "engines": {
     "bun": ">=1.0",
     "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
   }
 }

package/src/mcp-http.js

@@ -0,0 +1,110 @@
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+
+export const MCP_HTTP_SERVICE_NAME = 'knowledge';
+export const DEFAULT_MCP_HTTP_PORT = 8819;
+
+export function isHttpMode(argv = process.argv, env = process.env) {
+  return argv.includes('--http') || env.MCP_HTTP === '1';
+}
+
+export function resolveMcpHttpPort(argv = process.argv, env = process.env) {
+  const portIdx = argv.indexOf('--port');
+  if (portIdx !== -1 && argv[portIdx + 1]) {
+    return parsePort(argv[portIdx + 1], '--port');
+  }
+  if (env.MCP_HTTP_PORT) {
+    return parsePort(env.MCP_HTTP_PORT, 'MCP_HTTP_PORT');
+  }
+  return DEFAULT_MCP_HTTP_PORT;
+}
+
+function parsePort(raw, source) {
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+    throw new Error(`Invalid ${source} value "${raw}". Expected 0-65535.`);
+  }
+  return parsed;
+}
+
+async function readJsonBody(req) {
+  const chunks = [];
+  for await (const chunk of req) {
+    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  }
+  const text = Buffer.concat(chunks).toString('utf8');
+  if (!text) return undefined;
+  return JSON.parse(text);
+}
+
+export async function startMcpHttpServer(buildServer, options = {}) {
+  const host = options.host ?? '127.0.0.1';
+  const requestedPort = options.port ?? resolveMcpHttpPort();
+  const serviceName = options.serviceName ?? MCP_HTTP_SERVICE_NAME;
+
+  const httpServer = createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+
+      if (req.method === 'GET' && url.pathname === '/health') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ status: 'ok', name: serviceName }));
+        return;
+      }
+
+      if (url.pathname !== '/mcp') {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Not Found');
+        return;
+      }
+
+      const server = buildServer();
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+      });
+
+      await server.connect(transport);
+
+      let parsedBody;
+      if (req.method === 'POST') {
+        parsedBody = await readJsonBody(req);
+      }
+
+      await transport.handleRequest(req, res, parsedBody);
+
+      res.on('close', () => {
+        void transport.close();
+        void server.close();
+      });
+    } catch (error) {
+      console.error(`[${serviceName}-mcp] HTTP error:`, error);
+      if (!res.headersSent) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          jsonrpc: '2.0',
+          error: { code: -32603, message: 'Internal server error' },
+          id: null,
+        }));
+      }
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    httpServer.once('error', reject);
+    httpServer.listen(requestedPort, host, () => resolve());
+  });
+
+  const addr = httpServer.address();
+  const port = typeof addr === 'object' && addr ? addr.port : requestedPort;
+
+  console.error(`[${serviceName}-mcp] Streamable HTTP listening on http://${host}:${port}/mcp`);
+
+  return {
+    port,
+    host,
+    close: () =>
+      new Promise((resolve, reject) => {
+        httpServer.close((err) => (err ? reject(err) : resolve()));
+      }),
+  };
+}

package/src/mcp.js

@@ -0,0 +1,574 @@
+#!/usr/bin/env bun
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { defaultStorePath, loadStore, saveStore, makeId } from './store.ts';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+
+function createStoreSchema() {
+  return z.object({
+    store_path: z.string().optional().describe('Path to the store file (default: ~/.open-knowledge/db.json)'),
+  });
+}
+
+function createItemSchema() {
+  return z.object({
+    store_path: z.string().optional().describe('Path to the store file'),
+  });
+}
+
+function createAddSchema() {
+  return z.object({
+    title: z.string().describe('Item title'),
+    content: z.string().describe('Item content/body'),
+    tags: z.array(z.string()).optional().describe('Tags to attach'),
+    metadata: z.record(z.string(), z.unknown()).optional().describe('Metadata key-value pairs'),
+    store_path: z.string().optional().describe('Path to the store file'),
+  });
+}
+
+function createIdSchema() {
+  return z.object({
+    id: z.string().describe('Item ID or short ID'),
+    store_path: z.string().optional().describe('Path to the store file'),
+  });
+}
+
+function createListSchema() {
+  return z.object({
+    search: z.string().optional().describe('Search text for title/content'),
+    fuzzy: z.boolean().optional().describe('Use fuzzy matching for search'),
+    tag: z.array(z.string()).optional().describe('Filter by tags (must match all)'),
+    archived: z.boolean().optional().describe('Show only archived items'),
+    include_archived: z.boolean().optional().describe('Include archived items in results'),
+    page: z.number().optional().describe('Page number (default: 1)'),
+    limit: z.number().optional().describe('Items per page (default: 20)'),
+    sort: z.enum(['created', 'title']).optional().describe('Sort field'),
+    desc: z.boolean().optional().describe('Sort descending'),
+    after: z.string().optional().describe('Filter items created after ISO date'),
+    before: z.string().optional().describe('Filter items created before ISO date'),
+    store_path: z.string().optional().describe('Path to the store file'),
+  });
+}
+
+function createUpdateSchema() {
+  return z.object({
+    id: z.string().describe('Item ID or short ID'),
+    title: z.string().optional().describe('New title'),
+    content: z.string().optional().describe('New content'),
+    tags: z.array(z.string()).optional().describe('Tags to add'),
+    metadata: z.record(z.string(), z.unknown()).optional().describe('Metadata to merge'),
+    store_path: z.string().optional().describe('Path to the store file'),
+  });
+}
+
+function createDeleteSchema() {
+  return z.object({
+    id: z.string().describe('Item ID or short ID'),
+    confirm: z.boolean().describe('Must be true to confirm deletion'),
+    store_path: z.string().optional().describe('Path to the store file'),
+  });
+}
+
+function createUpsertSchema() {
+  return z.object({
+    id: z.string().describe('Item ID (used as id for new items)'),
+    title: z.string().optional().describe('Item title'),
+    content: z.string().optional().describe('Item content'),
+    tags: z.array(z.string()).optional().describe('Tags'),
+    metadata: z.record(z.string(), z.unknown()).optional().describe('Metadata'),
+    store_path: z.string().optional().describe('Path to the store file'),
+  });
+}
+
+function createBulkDeleteSchema() {
+  return z.object({
+    tag: z.array(z.string()).optional().describe('Delete items with these tags'),
+    search: z.string().optional().describe('Delete items matching search in title/content'),
+    confirm: z.boolean().describe('Must be true to confirm deletion'),
+    store_path: z.string().optional().describe('Path to the store file'),
+  });
+}
+
+function createExportSchema() {
+  return z.object({
+    file: z.string().optional().describe('Output file path (default: ./knowledge-export.json)'),
+    store_path: z.string().optional().describe('Path to the store file'),
+  });
+}
+
+function createImportSchema() {
+  return z.object({
+    file: z.string().describe('Path to exported JSON file'),
+    store_path: z.string().optional().describe('Path to the store file'),
+  });
+}
+
+function createStatsSchema() {
+  return z.object({
+    store_path: z.string().optional().describe('Path to the store file'),
+  });
+}
+
+function createBatchSchema() {
+  return z.object({
+    items: z.array(z.object({
+      id: z.string().optional(),
+      title: z.string(),
+      content: z.string(),
+      tags: z.array(z.string()).optional(),
+      metadata: z.record(z.string(), z.unknown()).optional(),
+      created_at: z.string().optional(),
+      updated_at: z.string().optional(),
+    })).describe('Array of items to import'),
+    store_path: z.string().optional().describe('Path to the store file'),
+  });
+}
+
+function createUntagSchema() {
+  return z.object({
+    id: z.string().describe('Item ID or short ID'),
+    tags: z.array(z.string()).describe('Tags to remove'),
+    store_path: z.string().optional().describe('Path to the store file'),
+  });
+}
+
+export function buildServer() {
+  const server = new McpServer({
+    name: 'open-knowledge',
+    version: '0.1.0',
+  });
+
+  // Helper to resolve store path
+  function resolveStore(path) {
+    return path || defaultStorePath();
+  }
+
+  server.registerTool('ok_add', {
+    title: 'Add a knowledge item',
+    description: 'Add a new item to the knowledge store with title, content, optional tags and metadata',
+    inputSchema: createAddSchema(),
+    handler: async ({ title, content, tags, metadata, store_path }) => {
+      const db = loadStore(resolveStore(store_path));
+      const now = new Date().toISOString();
+      const { id, shortId } = makeId();
+      const item = {
+        id,
+        short_id: shortId,
+        title,
+        content,
+        tags: tags ?? [],
+        metadata: metadata ?? {},
+        created_at: now,
+        updated_at: now,
+      };
+      db.items.push(item);
+      saveStore(resolveStore(store_path), db);
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ ok: true, item, message: `Added ${item.id}` }, null, 2) }],
+      };
+    },
+  });
+
+  server.registerTool('ok_list', {
+    title: 'List knowledge items',
+    description: 'List items with pagination, search, tag filter, date filter, and sorting',
+    inputSchema: createListSchema(),
+    handler: async ({ search, fuzzy, tag, archived, include_archived, page, limit, sort, desc, after, before, store_path }) => {
+      const db = loadStore(resolveStore(store_path));
+      let items = db.items;
+
+      if (search) {
+        const q = search.toLowerCase();
+        if (fuzzy) {
+          const levenshtein = (a, b) => {
+            const dp = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
+            for (let i = 0; i <= a.length; i += 1) dp[i][0] = i;
+            for (let j = 0; j <= b.length; j += 1) dp[0][j] = j;
+            for (let i = 1; i <= a.length; i += 1) {
+              for (let j = 1; j <= b.length; j += 1) {
+                const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+                dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+              }
+            }
+            return dp[a.length][b.length];
+          };
+          const scored = items.map((x) => {
+            const titleScore = levenshtein(q, x.title.toLowerCase());
+            const contentScore = Math.min(levenshtein(q, x.content.slice(0, 200).toLowerCase()), 20);
+            return { ...x, _fuzzyScore: Math.min(titleScore, contentScore) };
+          }).filter((x) => x._fuzzyScore <= 5);
+          scored.sort((a, b) => a._fuzzyScore - b._fuzzyScore);
+          items = scored;
+        } else {
+          items = items.filter((x) => x.title.toLowerCase().includes(q) || x.content.toLowerCase().includes(q));
+        }
+      }
+
+      if (tag && tag.length > 0) {
+        items = items.filter((x) => {
+          const itemTags = (x.tags ?? []).map((t) => t.toLowerCase());
+          return tag.every((t) => itemTags.includes(t.toLowerCase()));
+        });
+      }
+
+      if (archived) {
+        items = items.filter((x) => x.archived === true);
+      } else if (!include_archived) {
+        items = items.filter((x) => !x.archived);
+      }
+
+      if (after) {
+        items = items.filter((x) => x.created_at > after);
+      }
+      if (before) {
+        items = items.filter((x) => x.created_at < before);
+      }
+
+      const p = page ?? 1;
+      const l = limit ?? 20;
+      const start = (p - 1) * l;
+      const totalPages = Math.max(1, Math.ceil(items.length / l));
+      const rows = items.slice(start, start + l);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ page: p, limit: l, total: items.length, total_pages: totalPages, items: rows }, null, 2) }],
+      };
+    },
+  });
+
+  server.registerTool('ok_get', {
+    title: 'Get a knowledge item',
+    description: 'Retrieve a single item by its ID or short ID',
+    inputSchema: createIdSchema(),
+    handler: async ({ id, store_path }) => {
+      const db = loadStore(resolveStore(store_path));
+      const item = db.items.find((x) => x.id === id || x.short_id === id);
+      if (!item) {
+        return { content: [{ type: 'text', text: `Error: Item not found: ${id}` }] };
+      }
+      return { content: [{ type: 'text', text: JSON.stringify({ item }, null, 2) }] };
+    },
+  });
+
+  server.registerTool('ok_update', {
+    title: 'Update a knowledge item',
+    description: 'Update title, content, tags, or metadata of an existing item',
+    inputSchema: createUpdateSchema(),
+    handler: async ({ id, title, content, tags, metadata, store_path }) => {
+      const db = loadStore(resolveStore(store_path));
+      const item = db.items.find((x) => x.id === id || x.short_id === id);
+      if (!item) {
+        return { content: [{ type: 'text', text: `Error: Item not found: ${id}` }] };
+      }
+      if (title) item.title = title;
+      if (content) item.content = content;
+      if (tags) {
+        item.tags = [...new Set([...(item.tags ?? []), ...tags])];
+      }
+      if (metadata) {
+        item.metadata = { ...(item.metadata ?? {}), ...metadata };
+      }
+      item.updated_at = new Date().toISOString();
+      saveStore(resolveStore(store_path), db);
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, item }, null, 2) }] };
+    },
+  });
+
+  server.registerTool('ok_delete', {
+    title: 'Delete a knowledge item',
+    description: 'Permanently delete an item by ID. Requires confirm=true to prevent accidental deletion.',
+    inputSchema: createDeleteSchema(),
+    handler: async ({ id, confirm, store_path }) => {
+      if (!confirm) {
+        return { content: [{ type: 'text', text: 'Error: Refusing delete without confirm=true. Re-run with confirm: true.' }] };
+      }
+      const db = loadStore(resolveStore(store_path));
+      const before = db.items.length;
+      db.items = db.items.filter((x) => x.id !== id && x.short_id !== id);
+      if (db.items.length === before) {
+        return { content: [{ type: 'text', text: `Error: Item not found: ${id}` }] };
+      }
+      saveStore(resolveStore(store_path), db);
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, deleted_id: id }, null, 2) }] };
+    },
+  });
+
+  server.registerTool('ok_archive', {
+    title: 'Archive a knowledge item',
+    description: 'Soft-delete an item by setting its archived flag to true',
+    inputSchema: createIdSchema(),
+    handler: async ({ id, store_path }) => {
+      const db = loadStore(resolveStore(store_path));
+      const item = db.items.find((x) => x.id === id || x.short_id === id);
+      if (!item) {
+        return { content: [{ type: 'text', text: `Error: Item not found: ${id}` }] };
+      }
+      item.archived = true;
+      item.updated_at = new Date().toISOString();
+      saveStore(resolveStore(store_path), db);
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, item }, null, 2) }] };
+    },
+  });
+
+  server.registerTool('ok_restore', {
+    title: 'Restore a knowledge item',
+    description: 'Un-archive an item by setting its archived flag back to false',
+    inputSchema: createIdSchema(),
+    handler: async ({ id, store_path }) => {
+      const db = loadStore(resolveStore(store_path));
+      const item = db.items.find((x) => x.id === id || x.short_id === id);
+      if (!item) {
+        return { content: [{ type: 'text', text: `Error: Item not found: ${id}` }] };
+      }
+      item.archived = false;
+      item.updated_at = new Date().toISOString();
+      saveStore(resolveStore(store_path), db);
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, item }, null, 2) }] };
+    },
+  });
+
+  server.registerTool('ok_upsert', {
+    title: 'Upsert a knowledge item',
+    description: 'Create or update an item by ID. Creates new if ID does not exist, updates if it does.',
+    inputSchema: createUpsertSchema(),
+    handler: async ({ id, title, content, tags, metadata, store_path }) => {
+      const db = loadStore(resolveStore(store_path));
+      let item = db.items.find((x) => x.id === id || x.short_id === id);
+      const now = new Date().toISOString();
+      if (!item) {
+        if (!title || !content) {
+          return { content: [{ type: 'text', text: 'Error: New item requires both title and content.' }] };
+        }
+        const { shortId } = makeId();
+        item = {
+          id,
+          short_id: shortId,
+          title,
+          content,
+          tags: tags ?? [],
+          metadata: metadata ?? {},
+          created_at: now,
+          updated_at: now,
+        };
+        db.items.push(item);
+      } else {
+        if (title) item.title = title;
+        if (content) item.content = content;
+        if (tags) {
+          item.tags = [...new Set([...(item.tags ?? []), ...tags])];
+        }
+        if (metadata) {
+          item.metadata = { ...(item.metadata ?? {}), ...metadata };
+        }
+        item.updated_at = now;
+      }
+      saveStore(resolveStore(store_path), db);
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, item }, null, 2) }] };
+    },
+  });
+
+  server.registerTool('ok_untag', {
+    title: 'Remove tags from a knowledge item',
+    description: 'Remove specific tags from an item',
+    inputSchema: createUntagSchema(),
+    handler: async ({ id, tags, store_path }) => {
+      const db = loadStore(resolveStore(store_path));
+      const item = db.items.find((x) => x.id === id || x.short_id === id);
+      if (!item) {
+        return { content: [{ type: 'text', text: `Error: Item not found: ${id}` }] };
+      }
+      const removeTags = new Set(tags.map((t) => t.toLowerCase()));
+      const before = (item.tags ?? []).length;
+      item.tags = (item.tags ?? []).filter((t) => !removeTags.has(t.toLowerCase()));
+      const removed = before - item.tags.length;
+      item.updated_at = new Date().toISOString();
+      saveStore(resolveStore(store_path), db);
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, item, removed }, null, 2) }] };
+    },
+  });
+
+  server.registerTool('ok_bulk_delete', {
+    title: 'Bulk delete knowledge items',
+    description: 'Delete multiple items by tag or search pattern. Requires confirm=true.',
+    inputSchema: createBulkDeleteSchema(),
+    handler: async ({ tag, search, confirm, store_path }) => {
+      if (!confirm) {
+        return { content: [{ type: 'text', text: 'Error: Refusing bulk delete without confirm=true.' }] };
+      }
+      if (!tag && !search) {
+        return { content: [{ type: 'text', text: 'Error: Missing filter. Use tag or search to specify items.' }] };
+      }
+      const db = loadStore(resolveStore(store_path));
+      const before = db.items.length;
+      let items = db.items;
+
+      if (tag && tag.length > 0) {
+        items = items.filter((x) => {
+          const itemTags = (x.tags ?? []).map((t) => t.toLowerCase());
+          return tag.some((t) => itemTags.includes(t.toLowerCase()));
+        });
+      }
+
+      if (search) {
+        const q = search.toLowerCase();
+        items = items.filter((x) => x.title.toLowerCase().includes(q) || x.content.toLowerCase().includes(q));
+      }
+
+      const deleteIds = new Set(items.map((x) => x.id));
+      db.items = db.items.filter((x) => !deleteIds.has(x.id));
+      const deleted = before - db.items.length;
+      saveStore(resolveStore(store_path), db);
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, deleted }, null, 2) }] };
+    },
+  });
+
+  server.registerTool('ok_stats', {
+    title: 'Knowledge store statistics',
+    description: 'Get stats about the knowledge store: total items, tags, recent activity',
+    inputSchema: createStatsSchema(),
+    handler: async ({ store_path }) => {
+      const db = loadStore(resolveStore(store_path));
+      const items = db.items.filter((x) => !x.archived);
+      const total = items.length;
+      const tagCounts = {};
+      for (const item of items) {
+        for (const t of (item.tags ?? [])) {
+          tagCounts[t] = (tagCounts[t] ?? 0) + 1;
+        }
+      }
+      const now = new Date();
+      const today = now.toISOString().slice(0, 10);
+      const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString();
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          total,
+          created_today: items.filter((x) => x.created_at.slice(0, 10) === today).length,
+          created_week: items.filter((x) => x.created_at > weekAgo).length,
+          updated_week: items.filter((x) => x.updated_at && x.updated_at > weekAgo).length,
+          tags: Object.fromEntries(Object.entries(tagCounts).sort((a, b) => b[1] - a[1])),
+        }, null, 2) }],
+      };
+    },
+  });
+
+  server.registerTool('ok_export', {
+    title: 'Export knowledge items',
+    description: 'Export all items to a JSON file',
+    inputSchema: createExportSchema(),
+    handler: async ({ file, store_path }) => {
+      const db = loadStore(resolveStore(store_path));
+      const filePath = file || './knowledge-export.json';
+      writeFileSync(filePath, JSON.stringify(db, null, 2));
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, file: filePath, count: db.items.length }, null, 2) }] };
+    },
+  });
+
+  server.registerTool('ok_import', {
+    title: 'Import knowledge items',
+    description: 'Import items from an exported JSON file, skipping duplicates',
+    inputSchema: createImportSchema(),
+    handler: async ({ file, store_path }) => {
+      if (!existsSync(file)) {
+        return { content: [{ type: 'text', text: `Error: File not found: ${file}` }] };
+      }
+      const raw = readFileSync(file, 'utf8');
+      const imported = JSON.parse(raw);
+      if (!imported || !Array.isArray(imported.items)) {
+        return { content: [{ type: 'text', text: 'Error: Invalid import file: expected {"items": [...]}' }] };
+      }
+      const db = loadStore(resolveStore(store_path));
+      const existingIds = new Set(db.items.map((x) => x.id));
+      let added = 0;
+      for (const item of imported.items) {
+        if (!existingIds.has(item.id)) {
+          db.items.push(item);
+          added += 1;
+        }
+      }
+      saveStore(resolveStore(store_path), db);
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, added, skipped: imported.items.length - added }, null, 2) }] };
+    },
+  });
+
+  server.registerTool('ok_batch', {
+    title: 'Batch add knowledge items',
+    description: 'Add multiple items at once from an array of item objects',
+    inputSchema: createBatchSchema(),
+    handler: async ({ items, store_path }) => {
+      const db = loadStore(resolveStore(store_path));
+      const now = new Date().toISOString();
+      const existingIds = new Set(db.items.map((x) => x.id));
+      let added = 0;
+      let skipped = 0;
+      for (const entry of items) {
+        if (entry.id && existingIds.has(entry.id)) {
+          skipped += 1;
+          continue;
+        }
+        if (!entry.title || !entry.content) {
+          skipped += 1;
+          continue;
+        }
+        const ids = entry.id ? { id: entry.id, short_id: entry.short_id || null } : makeId();
+        const item = {
+          id: ids.id,
+          short_id: ids.short_id,
+          title: entry.title,
+          content: entry.content,
+          tags: entry.tags ?? [],
+          metadata: entry.metadata ?? {},
+          created_at: entry.created_at || now,
+          updated_at: entry.updated_at || now,
+        };
+        db.items.push(item);
+        added += 1;
+      }
+      saveStore(resolveStore(store_path), db);
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, added, skipped }, null, 2) }] };
+    },
+  });
+
+  return server;
+}
+
+function printHelp() {
+  console.error(`Usage: open-knowledge-mcp [options]
+
+Runs the @hasna/knowledge MCP server (stdio by default).
+
+Options:
+  --http            Serve MCP over Streamable HTTP (127.0.0.1)
+  --port <number>   HTTP port (default: 8819, env: MCP_HTTP_PORT)
+  -h, --help        Show this help text`);
+}
+
+async function main() {
+  if (process.argv.includes('-h') || process.argv.includes('--help')) {
+    printHelp();
+    return;
+  }
+
+  const { isHttpMode, resolveMcpHttpPort, startMcpHttpServer } = await import('./mcp-http.js');
+
+  if (isHttpMode()) {
+    const handle = await startMcpHttpServer(buildServer, {
+      port: resolveMcpHttpPort(),
+    });
+    process.on('SIGINT', () => void handle.close().finally(() => process.exit(0)));
+    process.on('SIGTERM', () => void handle.close().finally(() => process.exit(0)));
+    return;
+  }
+
+  const server = buildServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('open-knowledge MCP server running on stdio');
+}
+
+if (import.meta.main) {
+  main().catch((err) => {
+    console.error('MCP server error:', err);
+    process.exit(1);
+  });
+}

package/src/schema.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+export const itemSchema = z.object({
+  id: z.string().min(1),
+  short_id: z.string().nullable().optional(),
+  title: z.string().min(1),
+  content: z.string(),
+  tags: z.array(z.string()).default([]),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+  archived: z.boolean().default(false),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+export const storeSchema = z.object({
+  items: z.array(itemSchema.passthrough()).default([]),
+});
+
+export function validateItem(data) {
+  return itemSchema.parse(data);
+}
+
+export function validateStore(data) {
+  return storeSchema.parse(data);
+}

package/tests/cli.test.ts

@@ -34,11 +34,11 @@ describe('open-knowledge cli', () => {
   });
 
   test('version flag works', () => {
+    const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8')) as { version: string };
     const result = runCli(['--version']);
     expect(result.exitCode).toBe(0);
     const out = new TextDecoder().decode(result.stdout);
-    expect(out).toContain('@hasna/knowledge');
-    expect(out).toContain('0.1.0');
+    expect(out.trim()).toBe(pkg.version);
   });
 
   test('unknown command includes suggestion', () => {

package/tests/mcp-http.test.ts

@@ -0,0 +1,97 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { buildServer } from '../src/mcp.js';
+import {
+  DEFAULT_MCP_HTTP_PORT,
+  isHttpMode,
+  resolveMcpHttpPort,
+  startMcpHttpServer,
+} from '../src/mcp-http.js';
+
+const storePath = join(mkdtempSync(join(tmpdir(), 'knowledge-mcp-http-')), 'db.json');
+
+describe('knowledge MCP HTTP transport', () => {
+  test('defaults port to 8819', () => {
+    expect(DEFAULT_MCP_HTTP_PORT).toBe(8819);
+    expect(resolveMcpHttpPort(['node'], {})).toBe(8819);
+    expect(resolveMcpHttpPort(['node', '--port', '9001'], {})).toBe(9001);
+    expect(resolveMcpHttpPort(['node'], { MCP_HTTP_PORT: '9002' })).toBe(9002);
+  });
+
+  test('isHttpMode detects flag and env', () => {
+    expect(isHttpMode(['node'], {})).toBe(false);
+    expect(isHttpMode(['node', '--http'], {})).toBe(true);
+    expect(isHttpMode(['node'], { MCP_HTTP: '1' })).toBe(true);
+  });
+});
+
+describe('knowledge buildServer stdio registration', () => {
+  test('registers tools over in-memory transport', async () => {
+    const server = buildServer();
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await server.connect(serverTransport);
+
+    const client = new Client({ name: 'test', version: '0.0.0' });
+    await client.connect(clientTransport);
+
+    const tools = await client.listTools();
+    expect(tools.tools.some((tool) => tool.name === 'ok_stats')).toBe(true);
+
+    await client.close();
+    await server.close();
+  });
+});
+
+describe('knowledge streamable HTTP server', () => {
+  let handle: Awaited<ReturnType<typeof startMcpHttpServer>>;
+
+  beforeAll(async () => {
+    handle = await startMcpHttpServer(buildServer, { port: 0 });
+  });
+
+  afterAll(async () => {
+    await handle.close();
+  });
+
+  test('GET /health returns ok', async () => {
+    const res = await fetch(`http://${handle.host}:${handle.port}/health`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ status: 'ok', name: 'knowledge' });
+  });
+
+  test('initialize and call ok_stats over streamable HTTP', async () => {
+    const transport = new StreamableHTTPClientTransport(
+      new URL(`http://${handle.host}:${handle.port}/mcp`),
+    );
+    const client = new Client({ name: 'test', version: '0.0.0' });
+    await client.connect(transport);
+
+    const result = await client.callTool({ name: 'ok_stats', arguments: { store_path: storePath } });
+    expect(result.content).toBeDefined();
+    expect(Array.isArray(result.content)).toBe(true);
+
+    await client.close();
+  });
+
+  test('serves three concurrent clients from one process', async () => {
+    const clients = await Promise.all(
+      Array.from({ length: 3 }, async () => {
+        const transport = new StreamableHTTPClientTransport(
+          new URL(`http://${handle.host}:${handle.port}/mcp`),
+        );
+        const client = new Client({ name: 'test', version: '0.0.0' });
+        await client.connect(transport);
+        const tools = await client.listTools();
+        return { client, count: tools.tools.length };
+      }),
+    );
+
+    expect(clients.every((entry) => entry.count > 0)).toBe(true);
+    await Promise.all(clients.map((entry) => entry.client.close()));
+  });
+});