@appsoftwareltd/etherpk-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,95 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or chooses to license, to make, have made, use, sell, offer for sale,
+import and have imported the software, in each case subject to the limitations
+and conditions in this license. This license does not cover any patent claims
+that you cause to be infringed by modifications or additions to the software.
+If you or your company make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license for the software
+granted under these terms ends immediately. If your company makes such a claim,
+your patent license ends immediately for work on behalf of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will
+automatically be reinstated unless the licensor notifies you otherwise. If you
+violate these terms after reinstatement, your licenses will automatically and
+permanently terminate.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+## Definitions
+
+The *licensor* is the entity offering these terms, and the *software* is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+*you* refers to the individual or entity agreeing to these terms.
+
+*your company* is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+*control* means ownership of substantially all the assets of an entity, or the
+power to direct its management and legal policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+*your licenses* are all the licenses granted to you for the software under
+these terms.
+
+*use* includes copying, distributing, making available, modifying and, in each
+case, also for the purposes of your internal business operations.
+
+---
+
+Copyright (c) 2026 App Software Ltd (https://www.appsoftware.com)

package/README.md

@@ -0,0 +1,46 @@
+# @appsoftwareltd/etherpk-mcp
+
+The EtherPK **Headless Client**: an [MCP](https://modelcontextprotocol.io) server over one of
+your synced [EtherPK](https://etherpk.com) knowledge graphs, run on the same computer as your AI
+agent (Claude Code, Codex, Cursor and the like).
+
+EtherPK's Sync Server never sees your notes in the clear, so nothing hosted can serve them to an
+agent. This program signs in as one of your devices, holds your keys, keeps one graph in sync and
+speaks MCP to the agent beside it. Protected documents are listed by name and never served.
+
+Needs Node.js 22 or later.
+
+## Set up
+
+Open the graph in EtherPK, pick **Settings → Agents**, and copy the two commands it shows with your
+server and graph filled in. They are:
+
+```sh
+# Once per computer. Prompts for an account-wide Personal Access Token (from your Sync
+# Server's portal, Account → Tokens), then shows a short code to confirm in any unlocked
+# EtherPK tab - the same step as adding a phone.
+npx @appsoftwareltd/etherpk-mcp login --server https://sync.example.com
+
+# Tell the agent about the graph (Claude Code shown; the Agents tab has the others).
+claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --graph <graph id>
+```
+
+`npx @appsoftwareltd/etherpk-mcp graphs` lists the graphs the token can reach, by name and id.
+On a computer with no EtherPK tab to hand, `login --recovery-code` takes your Recovery Code
+instead (or `ETHERPK_RECOVERY_CODE` for a scripted setup; `ETHERPK_PAT` likewise).
+
+## What the agent gets
+
+`list_documents`, `read_document`, `search`, `backlinks`, `tasks`, `edit_document` (an exact,
+unique old→new replacement that merges with anyone typing elsewhere on the page),
+`append_document` (a page, or a day's journal entry, created if needed) and `create_page`.
+One running instance serves one graph.
+
+## Stopping it
+
+Revoke the token at the portal to cut the agent off, and `npx @appsoftwareltd/etherpk-mcp logout`
+to forget the token, keys and cached graphs on that computer. The keys live in
+`~/.config/etherpk/mcp.json` and the cached graphs under `~/.cache/etherpk/mcp/`, both readable
+only by your user - the same trust as a browser you have signed in on.
+
+Full guide: <https://docs.etherpk.com/using-ai-agents-with-your-notes>.

package/bin/etherpk-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/main.js'