@nesso-how/mcp 0.1.0-alpha.41 → 0.2.0-beta.0
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.
|
@@ -34,19 +34,19 @@
|
|
|
34
34
|
"slug": "guides/graph-management",
|
|
35
35
|
"title": "Graph management",
|
|
36
36
|
"description": "Working with multiple graphs, exporting and importing JSON, and desktop project folders.",
|
|
37
|
-
"markdown": "A **graph** is one map: its concepts, relations, and display settings. You can keep several graphs and switch between them, export or import any of them as JSON, and, on desktop, group graphs into project folders.\n\n## Multiple graphs\n\nThe **Sidebar** lists every graph in the current project. Click a graph to switch to it: the canvas, Inspector, and Review queue all follow.\n\n- **Rename**: double-click a graph's row in the list, type the new name, `Enter` to commit.\n- **Delete**: hover a row and click the trash icon. You're asked to confirm. Deleting also removes its file from the project folder on desktop. The last remaining graph can't be deleted, so the delete action is hidden when only one graph is left.\n- **New graph**: the **New** button above the list creates an empty graph and switches to it immediately.\n\nSwitching graphs flushes any pending autosave on the one you're leaving, so edits made just before a switch aren't lost.\n\n## Export and import (JSON)\n\nOpen the **⋯** menu in the top bar (tooltip: \"Export · Import · Shortcuts\") for:\n\n- **Export graph**: saves the active graph as a `.json` file named after the graph.\n- **Export graph (.png)**: renders the canvas at 1920×1200 and saves it as an image, with React Flow's selection handles excluded from the render.\n- **Import graph**: opens a file picker for a `.json` file and adds it as a new graph.\n\nExport behaves differently depending on platform:\n\n- **Desktop**: a native save dialog lets you pick the destination.\n- **Web**: if your browser supports the File System Access API, you get a save dialog and can overwrite the same file on repeat exports. Otherwise it falls back to a normal browser download.\n\nImporting a file that isn't a valid Nesso graph shows an error toast and imports nothing. A successful import creates a new graph (de-duplicating its name against your existing graphs) and switches to it.\n\nExported JSON carries graph **content** only: concepts, relations, and display settings. Personal review progress (FSRS data) is never included, so sharing or re-importing a file never carries someone else's recall history.\n\n## Desktop projects\n\nOn the desktop app, graphs live inside **project folders**: plain directories on disk holding one JSON file per graph plus a small manifest. The **Projects** section in the sidebar (desktop only) lists every folder you've opened and lets you switch between them.\n\n- **Add project**: the **+** button opens a native folder picker. Pick an existing project folder, or create a new one from the dialog's \"New Folder\" button (macOS). The selected folder becomes the active project.\n- **Switch project**: click any project in the list. The current graph is saved first, then the target folder's graphs load.\n- **Remove project**: hover a project and click the trash icon, then confirm. This only removes it from Nesso's list. Its files stay on disk untouched. You can't remove the last project in the list.\n- **Reveal in Finder**: hover a project and click the folder icon to reveal it in the system file manager.\n\nIf a project folder is moved, renamed, or deleted outside the app, it stays in the list marked as missing (greyed out, with a \"not found\" label) rather than disappearing. Switching away from a missing project happens automatically. Switching back works again once the folder reappears at the same path. Only the trash icon removes it from the list for good.\n\n:::caution\nNative folder pickers and the system menu bar are desktop-only Tauri APIs. None of this section applies to the web app, which has a single implicit workspace backed by IndexedDB. See [FAQ](../../faq/#what-changes-between-the-web-app-and-the-desktop-app) for the full web/desktop comparison.\n:::"
|
|
37
|
+
"markdown": "A **graph** is one map: its concepts, relations, and display settings. You can keep several graphs and switch between them, export or import any of them as JSON, and, on desktop, group graphs into project folders.\n\n## Multiple graphs\n\nThe **Sidebar** lists every graph in the current project. Click a graph to switch to it: the canvas, Inspector, and Review queue all follow.\n\n- **Rename**: double-click a graph's row in the list, type the new name, `Enter` to commit.\n- **Delete**: hover a row and click the trash icon. You're asked to confirm. Deleting also removes its file from the project folder on desktop. The last remaining graph can't be deleted, so the delete action is hidden when only one graph is left.\n- **New graph**: the **New** button above the list creates an empty graph and switches to it immediately.\n\nSwitching graphs flushes any pending autosave on the one you're leaving, so edits made just before a switch aren't lost.\n\n## Export and import (JSON)\n\nOpen the **⋯** menu in the top bar (tooltip: \"Export · Import · Shortcuts\") for:\n\n- **Export graph**: saves the active graph as a `.json` file named after the graph.\n- **Export graph (.png)**: renders the canvas at 1920×1200 and saves it as an image, with React Flow's selection handles excluded from the render.\n- **Import graph**: opens a file picker for a `.json` file and adds it as a new graph.\n\nExport behaves differently depending on platform:\n\n- **Desktop**: a native save dialog lets you pick the destination.\n- **Web**: if your browser supports the File System Access API, you get a save dialog and can overwrite the same file on repeat exports. Otherwise it falls back to a normal browser download.\n\nImporting a file that isn't a valid Nesso graph shows an error toast and imports nothing. A successful import creates a new graph (de-duplicating its name against your existing graphs) and switches to it.\n\nExported JSON carries graph **content** only: concepts, relations, and display settings. Personal review progress (FSRS data) is never included, so sharing or re-importing a file never carries someone else's recall history.\n\n## File compatibility\n\nNesso graph files carry separate envelope and vocabulary versions. When you\nimport a file or open a desktop project, released older beta formats are\nupgraded through sequential compatibility steps. A file created by a newer\nunsupported Nesso version is rejected so its data is not interpreted\nincorrectly.\n\nThe first supported baseline is the definition-only graph shape introduced\nbefore `0.2.0-beta.0`. Earlier alpha-only `examples`, `notes`, and image\nfields are not migrated. Review scheduling state is stored separately and is\nnot included in exported graph files.\n\n## Desktop projects\n\nOn the desktop app, graphs live inside **project folders**: plain directories on disk holding one JSON file per graph plus a small manifest. The **Projects** section in the sidebar (desktop only) lists every folder you've opened and lets you switch between them.\n\n- **Add project**: the **+** button opens a native folder picker. Pick an existing project folder, or create a new one from the dialog's \"New Folder\" button (macOS). The selected folder becomes the active project.\n- **Switch project**: click any project in the list. The current graph is saved first, then the target folder's graphs load.\n- **Remove project**: hover a project and click the trash icon, then confirm. This only removes it from Nesso's list. Its files stay on disk untouched. You can't remove the last project in the list.\n- **Reveal in Finder**: hover a project and click the folder icon to reveal it in the system file manager.\n\nIf a project folder is moved, renamed, or deleted outside the app, it stays in the list marked as missing (greyed out, with a \"not found\" label) rather than disappearing. Switching away from a missing project happens automatically. Switching back works again once the folder reappears at the same path. Only the trash icon removes it from the list for good.\n\nIf every file in a project folder uses a vocabulary or format version that this release of Nesso cannot read, the project is blocked: Nesso does not switch to it, does not create new files inside it, and does not overwrite any of the unsupported files. A banner explains what happened, and the previous project stays active. See [Troubleshooting](../../troubleshooting/#unsupported-project-files-desktop) for recovery steps.\n\n:::caution\nNative folder pickers and the system menu bar are desktop-only Tauri APIs. None of this section applies to the web app, which has a single implicit workspace backed by IndexedDB. See [FAQ](../../faq/#what-changes-between-the-web-app-and-the-desktop-app) for the full web/desktop comparison.\n:::"
|
|
38
38
|
},
|
|
39
39
|
{
|
|
40
40
|
"slug": "guides/mcp",
|
|
41
41
|
"title": "MCP",
|
|
42
42
|
"description": "Connect Nesso to Claude, Cursor, or any MCP-compatible AI client.",
|
|
43
|
-
"markdown": "The `@nesso-how/mcp` package is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI clients access to Nesso documentation, the full relation-type vocabulary, and tools to **build** and **validate** graph documents. Once connected, models can answer questions about how Nesso works, produce importable graph JSON, and check files before writing them back to disk.\n\n## Setup\n\n### Claude Desktop\n\nOpen `claude_desktop_config.json`. On macOS it lives at `~/Library/Application Support/Claude/claude_desktop_config.json`; on Windows at `%APPDATA%\\Claude\\claude_desktop_config.json`.\n\nAdd a `nesso` entry under `mcpServers`:\n\n```json\n{\n \"mcpServers\": {\n \"nesso\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@nesso-how/mcp\"]\n }\n }\n}\n```\n\nSave the file and restart Claude Desktop. The Nesso tools will be available to the model automatically.\n\n### Cursor\n\nOpen **Settings -> MCP** and add a new server with command `npx` and args `[\"-y\", \"@nesso-how/mcp\"]`.\n\n### Other MCP clients\n\nAny client that speaks the stdio MCP transport works. Run `npx -y @nesso-how/mcp` as the server command. No other configuration is required.\n\n## What it can do\n\nOnce connected, you can ask your AI client things like:\n\n- \"What relation types does Nesso support?\" (uses `get_relation_types`)\n- \"Show me the Nesso getting started guide\" (uses `get_nesso_docs`)\n- \"Build a graph about photosynthesis with causes and enables relations\" (uses `build_graph`)\n- \"Validate this graph JSON before I save it\" (uses `validate_graph`)\n\nThe MCP server is **stateless** and does not read or write files. Your client uses its own filesystem tools to read `.json` graph files, passes the contents inline to `validate_graph` or `build_graph`, and writes the result back. Nesso picks up external edits through its normal workspace sync.\n\n### Agent workflow for graph files\n\nA typical end-to-end flow when the client has filesystem access:\n\n1. **Read** the target graph `.json` from the project folder (client filesystem tool).\n2. **Validate** with `validate_graph`. Fix any `errors` before saving. Review `warnings` (e.g. missing
|
|
43
|
+
"markdown": "The `@nesso-how/mcp` package is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI clients access to Nesso documentation, the full relation-type vocabulary, and tools to **build** and **validate** graph documents. Once connected, models can answer questions about how Nesso works, produce importable graph JSON, and check files before writing them back to disk.\n\n## Setup\n\n### Claude Desktop\n\nOpen `claude_desktop_config.json`. On macOS it lives at `~/Library/Application Support/Claude/claude_desktop_config.json`; on Windows at `%APPDATA%\\Claude\\claude_desktop_config.json`.\n\nAdd a `nesso` entry under `mcpServers`:\n\n```json\n{\n \"mcpServers\": {\n \"nesso\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@nesso-how/mcp\"]\n }\n }\n}\n```\n\nSave the file and restart Claude Desktop. The Nesso tools will be available to the model automatically.\n\n### Cursor\n\nOpen **Settings -> MCP** and add a new server with command `npx` and args `[\"-y\", \"@nesso-how/mcp\"]`.\n\n### Other MCP clients\n\nAny client that speaks the stdio MCP transport works. Run `npx -y @nesso-how/mcp` as the server command. No other configuration is required.\n\n## What it can do\n\nOnce connected, you can ask your AI client things like:\n\n- \"What relation types does Nesso support?\" (uses `get_relation_types`)\n- \"Show me the Nesso getting started guide\" (uses `get_nesso_docs`)\n- \"Build a graph about photosynthesis with causes and enables relations\" (uses `build_graph`)\n- \"Validate this graph JSON before I save it\" (uses `validate_graph`)\n\nThe MCP server is **stateless** and does not read or write files. Your client uses its own filesystem tools to read `.json` graph files, passes the contents inline to `validate_graph` or `build_graph`, and writes the result back. Nesso picks up external edits through its normal workspace sync.\n\n### Agent workflow for graph files\n\nA typical end-to-end flow when the client has filesystem access:\n\n1. **Read** the target graph `.json` from the project folder (client filesystem tool).\n2. **Validate** with `validate_graph`. Fix any `errors` before saving; missing or foreign `vocabulary` is a hard error that rejects the file. Review `warnings` (e.g. a missing relation `type`).\n3. **Build or extend** with `build_graph` when creating a new graph from structured concepts and relations: the tool assigns ids, vocabulary metadata, valid relation types, and layout positions.\n4. **Re-validate** the output with `validate_graph` if the client edited the JSON by hand.\n5. **Write** the JSON back to disk (client filesystem tool). Open or sync the graph in Nesso.\n\nExample prompt:\n\n> Read `graphs/biology.json` in this workspace, validate it with Nesso MCP, then use `build_graph` to add concepts \"Chloroplast\" and \"Glucose\" linked by `produces`, merge the result, re-validate, and write the file back.\n\nSee [MCP tools](../../reference/mcp-tools/) for the full tool reference."
|
|
44
44
|
},
|
|
45
45
|
{
|
|
46
46
|
"slug": "guides/review-mode",
|
|
47
47
|
"title": "Review mode",
|
|
48
48
|
"description": "Spaced-repetition review of your concepts with FSRS, how it queues cards and reschedules them from your self-ratings.",
|
|
49
|
-
"markdown": "Press `R` (or open the **Review** pill in the top bar) to start a focused study session. Review surfaces concepts that are due, prompts you to recall what you know, and reschedules them based on how you self-rate.\n\nNesso uses [FSRS](https://github.com/open-spaced-repetition/ts-fsrs), a modern open-source successor to the SM-2 / Anki algorithm.\n\n## What gets reviewed\n\nEach concept node carries its own FSRS state: `stability`, `difficulty`, `due`, `lastReview`, `lastRating`, and friends. A node is **due** when `due <= now`. New, unrated concepts default to `due = 0`, which means they show up immediately the first time you open Review.\n\nThe session queue is built fresh every time you open the overlay: all due nodes, sorted by urgency, in random order within the same due bucket.\n\n## Flow\n\nFor each due concept, Review:\n\n1. **Shows the concept title** and a short recall prompt. Try to remember its definition and typed relations before revealing.\n2. **Waits for you to think**, then click **Reveal** (or press `Space`).\n3. **Reveals** the concept's definition and typed relations.\n4. **You rate** how it felt: `Again`, `Hard`, `Good`, `Easy`. Each button shows the **predicted next interval** under it (e.g.
|
|
49
|
+
"markdown": "Press `R` (or open the **Review** pill in the top bar) to start a focused study session. Review surfaces concepts that are due, prompts you to recall what you know, and reschedules them based on how you self-rate.\n\nNesso uses [FSRS](https://github.com/open-spaced-repetition/ts-fsrs), a modern open-source successor to the SM-2 / Anki algorithm.\n\n## What gets reviewed\n\nEach concept node carries its own FSRS state: `stability`, `difficulty`, `due`, `lastReview`, `lastRating`, and friends. A node is **due** when `due <= now`. New, unrated concepts default to `due = 0`, which means they show up immediately the first time you open Review.\n\nThe session queue is built fresh every time you open the overlay: all due nodes, sorted by urgency, in random order within the same due bucket.\n\n## Daily reminder\n\nWhen a concept you have already studied becomes due, Nesso can show a reminder after you open its graph. The reminder appears at most once per local calendar day for each graph. New concepts do not trigger it, although they still join the normal queue when you choose **Start review**.\n\nClosing the reminder suppresses it for that graph for the rest of the day. **Start review** opens the same unfiltered Review session as the top-bar pill.\n\n## Flow\n\nFor each due concept, Review:\n\n1. **Shows the concept title** and a short recall prompt. Try to remember its definition and typed relations before revealing.\n2. **Waits for you to think**, then click **Reveal** (or press `Space`).\n3. **Reveals** the concept's definition and typed relations.\n4. **You rate** how it felt: `Again`, `Hard`, `Good`, `Easy`. Each button shows the **predicted next interval** under it (e.g. `5 min`, `2 hours`, `4 days`, `2 months`, localized to your language).\n\nFSRS then updates `stability` and `difficulty`, schedules the next `due` date, and Review advances to the next card. Done with the queue, the overlay closes. You're caught up.\n\n## Tuning FSRS\n\nUnder **Settings → Learning → Review**:\n\n| Setting | What it does | Range |\n| -------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------- |\n| **Review reminder** | Shows a daily reminder when concepts you have studied are due. This can be disabled independently of **Review mode**. | On/off |\n| **Target retention** | Probability of correctly recalling a concept at its next review. Higher means more frequent reviews. | 70% to 97% |\n| **Max interval** | Longest interval FSRS can schedule, in days. Caps how far into the future a card can be pushed. | 1 to 36,500 |\n\nThe defaults (90% retention, 100-year cap) match the FSRS reference defaults. Lower the retention if you're comfortable forgetting more in exchange for fewer reviews. Raise the max interval if you want long-term cards to keep stretching out.\n\nReview is on by default. The **Review mode** toggle at the top of **Settings → Learning** turns it off entirely: the **Review** pill and the `R` shortcut disappear, and the FSRS settings above hide while it is off. The **Review reminder** toggle remains available independently, but reminders only appear while **Review mode** is enabled.\n\n## Tips\n\n- Add a **definition** in the Inspector. It appears on reveal and gives you something concrete to check your recall against.\n- Pair concepts with **at least one typed edge** before reviewing them. Relations are part of what you reveal and what makes the graph worth remembering.\n- The session count in the top bar reflects the original queue size. Cards rated `Again` that come back later increase the count past 100%. That is expected."
|
|
50
50
|
},
|
|
51
51
|
{
|
|
52
52
|
"slug": "introduction",
|
|
@@ -58,7 +58,7 @@
|
|
|
58
58
|
"slug": "reference/mcp-tools",
|
|
59
59
|
"title": "MCP tools",
|
|
60
60
|
"description": "Reference for the four tools exposed by the @nesso-how/mcp server.",
|
|
61
|
-
"markdown": "The `@nesso-how/mcp` server exposes four tools. See [MCP](../../guides/mcp/) for setup and workflow.\n\n### `get_nesso_docs`\n\nFetches documentation pages from this site. Call it without a `slug` to get a table of contents, or with a slug (e.g. `\"guides/getting-started\"`) to get the full page content.\n\n### `get_relation_types`\n\nReturns the complete list of relation types grouped by category id (`taxonomic`, `structural`, and so on from `RELATION_CATEGORIES` in `@nesso-how/vocab-learning`), with glyph, symmetry, and type properties (transitive, inverse, strength, polarity, cardinality). Use this whenever you need valid type names for graph JSON or explanations for the learner.\n\n### `validate_graph`\n\n**Input:** `{ \"graph\": \"<json string>\" }`: a Nesso graph document (`concepts[]`, `relations[]`), not runtime React Flow `nodes`/`edges`.\n\n**Output:** `{ \"valid\": boolean, \"errors\": [{ \"path\", \"message\" }], \"warnings\": [{ \"path\", \"message\" }] }`\n\nRuns envelope and vocabulary validation
|
|
61
|
+
"markdown": "The `@nesso-how/mcp` server exposes four tools. See [MCP](../../guides/mcp/) for setup and workflow.\n\n### `get_nesso_docs`\n\nFetches documentation pages from this site. Call it without a `slug` to get a table of contents, or with a slug (e.g. `\"guides/getting-started\"`) to get the full page content.\n\n### `get_relation_types`\n\nReturns the complete list of relation types grouped by category id (`taxonomic`, `structural`, and so on from `RELATION_CATEGORIES` in `@nesso-how/vocab-learning`), with glyph, symmetry, and type properties (transitive, inverse, strength, polarity, cardinality). Use this whenever you need valid type names for graph JSON or explanations for the learner.\n\n### `validate_graph`\n\n**Input:** `{ \"graph\": \"<json string>\" }`: a Nesso graph document (`concepts[]`, `relations[]`), not runtime React Flow `nodes`/`edges`.\n\n**Output:** `{ \"valid\": boolean, \"errors\": [{ \"path\", \"message\" }], \"warnings\": [{ \"path\", \"message\" }] }`\n\nRuns the same envelope and vocabulary validation used by the app: it accepts the\ncurrent protected baseline, rejects newer unsupported envelope versions, and\nrejects unsupported alpha elaboration fields. Also performs structural checks:\nduplicate ids, dangling relation endpoints, and unknown relation types.\n\n`valid` is `true` only when `errors` is empty. The tool returns diagnostics\nonly; it does not produce rewritten or migrated JSON.\n\n### `build_graph`\n\n**Input:**\n\n```json\n{\n \"name\": \"Photosynthesis\",\n \"concepts\": [\n \"Sunlight\",\n {\n \"text\": \"Chloroplast\",\n \"elaboration\": { \"definition\": \"...\" }\n }\n ],\n \"relations\": [{ \"from\": \"Sunlight\", \"to\": \"Chloroplast\", \"relation\": \"enables\" }]\n}\n```\n\n- `concepts`: label strings or objects with optional `id`, `text`, and `elaboration`.\n- `relations`: `from` / `to` match concept `id` or label (must be unambiguous); `relation` must be a valid type id from `get_relation_types`.\n\n**Output:** Pretty-printed graph document JSON ready to write to disk (includes `vocabulary`, generated ids, and dagre layout positions). FSRS review fields and React Flow edge shape (`type: \"nesso\"`, handles) are applied by the app on import, not stored in the file."
|
|
62
62
|
},
|
|
63
63
|
{
|
|
64
64
|
"slug": "reference/relation-types",
|
|
@@ -70,7 +70,7 @@
|
|
|
70
70
|
"slug": "troubleshooting",
|
|
71
71
|
"title": "Troubleshooting",
|
|
72
72
|
"description": "What to do when a banner, the mentor, or an update check doesn't behave as expected.",
|
|
73
|
-
"markdown": "## \"This graph was changed on disk while you were editing\"\n\n**When it appears**: desktop only. The file watcher noticed the active graph's JSON file changed outside the app (an external editor, a sync tool, another Nesso window) while you had unsaved edits in memory.\n\nThe banner offers two actions:\n\n- **Keep my changes**: writes your in-memory version to disk, overwriting the external change.\n- **Reload from disk**: discards your in-memory edits and loads the file as it now is on disk. Undo/redo history is cleared in the process.\n\nThere's no automatic merge: pick whichever side of the conflict you want to keep.\n\n## Auto-update problems (desktop)\n\nThe desktop app checks GitHub Releases once on launch. If checking fails (offline, GitHub unreachable), it stays silent: no banner, no error, just no update for now.\n\nOnce an update is found, the banner can show:\n\n- **Version `X` is available**: click **Install & restart** to download and apply it.\n- **Installing…**: download/install in progress; the button is disabled and there is no way to cancel.\n- **Update failed. Try again?**: the download or install step failed (e.g. lost connectivity mid-download). Click **Retry**.\n- **Update installed. Restart Nesso to finish**: the update was applied to disk, but the app couldn't relaunch itself automatically. Quit and reopen Nesso manually.\n\nYou can dismiss the available/error states for the rest of the session with the banner's close button; the install-in-progress state has no dismiss, since the install can't be cancelled once started.\n\n## Mentor not responding\n\nIf a mentor message fails, the reply bubble shows one of two messages, depending on what went wrong:\n\n- **Can't reach the AI endpoint. Check Settings (`⌘,`) → AI. For local Ollama, run `ollama serve`.** A network-level failure: the endpoint is unreachable, the wrong port, or, on the hosted web app, a CORS rejection from a local Ollama instance. Confirm the base URL in **Settings → AI**, that Ollama or your server is actually running, and, if you're on the hosted web app talking to local Ollama, that you started it with `OLLAMA_ORIGINS` set to the app's origin (see [AI mentor](../guides/ai-mentor/#reaching-local-ollama-from-the-hosted-app)).\n- **_Hmm._ My voice failed me. Try again, slowly.** The endpoint was reachable but returned an error or a response Nesso couldn't parse. Check the model name and that the endpoint speaks the OpenAI-compatible `chat/completions` format.\n\nDesktop mentor requests use the native HTTP client. The desktop capability allows HTTPS and loopback HTTP only. If a desktop endpoint uses non-loopback `http://`, switch it to `https://` or configure a local service on `localhost`, `127.0.0.1`, or `::1`. Browser requests continue to follow normal browser CORS rules.\n\nClosing the mentor panel, switching graphs, or clicking **New chat** aborts any in-flight request without showing an error.\n\n## \"No AI endpoint configured\"\n\nThis isn't a failure: it's the mentor's resting state until you've set up an endpoint. It appears whenever **Mentor** is enabled in **Settings → AI** but the base URL or model field is empty. The input stays disabled until both are filled in. See [AI mentor](../guides/ai-mentor/#connecting-a-model) for setup.\n\n## Model pull stalls or shows stale results\n\nModel pulling is available only for local Ollama endpoints. When you click **Pull** in **Settings → AI**, Nesso streams the download progress from Ollama's `/api/pull` endpoint.\n\nIf a pull appears stuck:\n\n- **Changing settings cancels the pull.** Switching the model, base URL, or API key, disabling the mentor toggle, or closing the **Settings** dialog all abort the in-flight pull so stale progress cannot interfere with a new model selection.\n- **Ollama must be reachable on the native port.** Nesso strips the `/v1` suffix from your base URL to reach Ollama's native `/api/pull` endpoint. If you configured a non-standard port, make sure Ollama's native API is running on that same port.\n- **Progress is purely cosmetic.** The pull runs to completion regardless of whether the progress bar is visible. If the pull completes while you are on a different settings tab, the status badge updates when you return to the AI tab.\n\nIf the status shows **Unauthorized**, check your API key. The endpoint rejected the request with HTTP `401` or `403`. For hosted providers, make sure the key is valid and has not expired. Local Ollama instances do not require an API key
|
|
73
|
+
"markdown": "## \"This graph was changed on disk while you were editing\"\n\n**When it appears**: desktop only. The file watcher noticed the active graph's JSON file changed outside the app (an external editor, a sync tool, another Nesso window) while you had unsaved edits in memory.\n\nThe banner offers two actions:\n\n- **Keep my changes**: writes your in-memory version to disk, overwriting the external change.\n- **Reload from disk**: discards your in-memory edits and loads the file as it now is on disk. Undo/redo history is cleared in the process.\n\nThere's no automatic merge: pick whichever side of the conflict you want to keep.\n\n## Auto-update problems (desktop)\n\nThe desktop app checks GitHub Releases once on launch. If checking fails (offline, GitHub unreachable), it stays silent: no banner, no error, just no update for now.\n\nOnce an update is found, the banner can show:\n\n- **Version `X` is available**: click **Install & restart** to download and apply it.\n- **Installing…**: download/install in progress; the button is disabled and there is no way to cancel.\n- **Update failed. Try again?**: the download or install step failed (e.g. lost connectivity mid-download). Click **Retry**.\n- **Update installed. Restart Nesso to finish**: the update was applied to disk, but the app couldn't relaunch itself automatically. Quit and reopen Nesso manually.\n\nYou can dismiss the available/error states for the rest of the session with the banner's close button; the install-in-progress state has no dismiss, since the install can't be cancelled once started.\n\n## Unsupported project files (desktop)\n\nIf you open a project folder whose graph files come from a newer Nesso version or use an unknown vocabulary, Nesso blocks the project and shows a yellow info banner:\n\n> This project contains N file(s) not supported by this version of Nesso. Please update the app or remove the files manually.\n\n**What happens**: the project folder stays intact on disk. Nesso does not create new graphs inside it, does not overwrite any of the unsupported files, and does not switch to that project; the current (previously loaded) project remains active.\n\n**How to recover**:\n\n- **Update Nesso** if a newer release supports those files.\n- **Remove the unsupported files manually** from the project folder (Finder / File Explorer), then switch back to the project. Nesso will treat it as an empty project and seed one starter graph.\n- **Open a different project** from the sidebar; the blocked project stays in your list, greyed out, until you resolve it.\n\n## Mentor not responding\n\nIf a mentor message fails, the reply bubble shows one of two messages, depending on what went wrong:\n\n- **Can't reach the AI endpoint. Check Settings (`⌘,`) → AI. For local Ollama, run `ollama serve`.** A network-level failure: the endpoint is unreachable, the wrong port, or, on the hosted web app, a CORS rejection from a local Ollama instance. Confirm the base URL in **Settings → AI**, that Ollama or your server is actually running, and, if you're on the hosted web app talking to local Ollama, that you started it with `OLLAMA_ORIGINS` set to the app's origin (see [AI mentor](../guides/ai-mentor/#reaching-local-ollama-from-the-hosted-app)).\n- **_Hmm._ My voice failed me. Try again, slowly.** The endpoint was reachable but returned an error or a response Nesso couldn't parse. Check the model name and that the endpoint speaks the OpenAI-compatible `chat/completions` format.\n\nDesktop mentor requests use the native HTTP client. The desktop capability allows HTTPS and loopback HTTP only. If a desktop endpoint uses non-loopback `http://`, switch it to `https://` or configure a local service on `localhost`, `127.0.0.1`, or `::1`. Browser requests continue to follow normal browser CORS rules.\n\nClosing the mentor panel, switching graphs, or clicking **New chat** aborts any in-flight request without showing an error.\n\n## \"No AI endpoint configured\"\n\nThis isn't a failure: it's the mentor's resting state until you've set up an endpoint. It appears whenever **Mentor** is enabled in **Settings → AI** but the base URL or model field is empty. The input stays disabled until both are filled in. See [AI mentor](../guides/ai-mentor/#connecting-a-model) for setup.\n\n## Model pull stalls or shows stale results\n\nModel pulling is available only for local Ollama endpoints. When you click **Pull** in **Settings → AI**, Nesso streams the download progress from Ollama's `/api/pull` endpoint.\n\nIf a pull appears stuck:\n\n- **Changing settings cancels the pull.** Switching the model, base URL, or API key, disabling the mentor toggle, or closing the **Settings** dialog all abort the in-flight pull so stale progress cannot interfere with a new model selection.\n- **Ollama must be reachable on the native port.** Nesso strips the `/v1` suffix from your base URL to reach Ollama's native `/api/pull` endpoint. If you configured a non-standard port, make sure Ollama's native API is running on that same port.\n- **Progress is purely cosmetic.** The pull runs to completion regardless of whether the progress bar is visible. If the pull completes while you are on a different settings tab, the status badge updates when you return to the AI tab.\n\nIf the status shows **Unauthorized**, check your API key. The endpoint rejected the request with HTTP `401` or `403`. For hosted providers, make sure the key is valid and has not expired. Local Ollama instances do not require an API key; leave the field empty."
|
|
74
74
|
}
|
|
75
75
|
]
|
|
76
76
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nesso-how/mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0-beta.0",
|
|
4
4
|
"description": "MCP server exposing Nesso knowledge graph tools to LLM clients",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -23,12 +23,13 @@
|
|
|
23
23
|
"dagre": "^0.8.5",
|
|
24
24
|
"zod": "^4.4.3",
|
|
25
25
|
"@modelcontextprotocol/server": "^2.0.0-alpha.2",
|
|
26
|
-
"@nesso-how/vocab-learning": "0.
|
|
26
|
+
"@nesso-how/vocab-learning": "0.2.0-beta.0"
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
29
|
"@types/dagre": "^0.7.53",
|
|
30
30
|
"@types/node": "^22.0.0",
|
|
31
|
-
"typescript": "~5.8.3"
|
|
31
|
+
"typescript": "~5.8.3",
|
|
32
|
+
"@nesso-how/schema": "0.2.0-beta.0"
|
|
32
33
|
},
|
|
33
34
|
"scripts": {
|
|
34
35
|
"bundle-docs": "node scripts/bundle-starlight-docs.mjs",
|