@nesso-how/mcp 0.1.0-alpha.33 → 0.1.0-alpha.34
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.
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @nesso-how/mcp
|
|
2
2
|
|
|
3
|
-
[MCP](https://modelcontextprotocol.io/) server for [Nesso](https://nesso.how) — relation types and docs for LLM clients.
|
|
3
|
+
[MCP](https://modelcontextprotocol.io/) server for [Nesso](https://nesso.how) — relation types from the graph vocabulary and bundled docs for LLM clients.
|
|
4
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
@@ -4,13 +4,13 @@
|
|
|
4
4
|
"slug": "guides/ai-mentor",
|
|
5
5
|
"title": "AI mentor (Socrates)",
|
|
6
6
|
"description": "How the Socratic mentor works, connecting a model, persona, and graph-aware context.",
|
|
7
|
-
"markdown": ":::caution\nThis is the part of Nesso with the most potential and the most room to grow. Small models tend to drift out of the Socratic role and start explaining rather than questioning. A larger remote model works noticeably better. Improving the mentor is where most of the future work is headed.\n:::\n\nClick the **Socrates**
|
|
7
|
+
"markdown": ":::caution\nThis is the part of Nesso with the most potential and the most room to grow. Small models tend to drift out of the Socratic role and start explaining rather than questioning. A larger remote model works noticeably better. Improving the mentor is where most of the future work is headed.\n:::\n\nClick the **Socrates** entry in the **status bar** (bottom-left) to start a dialogue. The mentor reads your current graph and selection, and replies with **questions rather than explanations**. The goal is to surface what you understand and where the gaps are.\n\n## How it works\n\nEvery send rebuilds a system prompt from the live store: a snapshot of up to ~60 concept nodes, sorted weakest-first via **`nodeStrength()`** ([`context.ts`](https://github.com/nesso-how/nesso/blob/main/src/llm/context.ts)): **FSRS stability** dominates ordering, **Again/Hard** nudge weaker items up, overdue is only a slight tie-break. Each node line lists stability (`s=` days), days since last review, last FSRS rating, and `DUE` when the scheduler says so, plus typed edges (~2× the node allowance), current selection when any, and focal-neighbour context when a node is selected (`Focus:` / `Related:` lines). The conversation history stays in the mentor card and is reset when you switch graphs or click **New chat**.\n\nChat history is **not persisted**. It lives only for the current panel session.\n\n## Connecting a model\n\nThe mentor is **experimental** and runs against any OpenAI-compatible `chat/completions` endpoint. Configure it under **Settings -> AI**: base URL, model, and an optional API key.\n\nThe default targets a local [Ollama](https://ollama.com/) instance (`http://localhost:11434/v1`, model `gemma3:4b`). Install Ollama, pull a model, and the mentor works with nothing leaving your machine. Any hosted OpenAI-compatible endpoint works too; set the API key it expects.\n\nThere is **no built-in in-browser model**. Nesso previously bundled a small WebGPU model, but it was too small and slow to be useful and has been removed. Until a reachable endpoint is configured, the chat input stays disabled and the mentor shows a short setup hint.\n\n### Reaching local Ollama from the hosted app\n\nIf you use the hosted web app over HTTPS, requests to `http://localhost:11434` are allowed (localhost is exempt from mixed-content blocking), but Ollama still rejects the cross-origin request unless you allow the app's origin: start it with `OLLAMA_ORIGINS=https://app.nesso.how` (or run the desktop build, where this does not apply).\n\n## The Socratic persona\n\nThe system prompt (`getMentorBase` in [`MentorPanel.tsx`](https://github.com/nesso-how/nesso/blob/main/src/components/mentor/MentorPanel.tsx)) shapes Socrates:\n\n- One short question per turn by default; explain only enough to frame the question.\n- Replies are soft-capped at ~200 words (hard cap via output tokens).\n- No graph edits proposed in dialogue. Socrates probes; the user edits.\n- No emojis, flattery, JSON, or pseudo-graph markup. Sparse `*asterisks*` on key terms.\n- Replies in the active UI language (English or Italian). Snapshot tokens stay **English-shaped** (`s=…d`, `…d since review`, etc.), with the same spelling in the legend for every locale.\n\nIf you want a more permissive coach, fork the persona. It is plain text in the component and easy to swap.\n\n## Opening message\n\nWhen the panel opens, the mentor sends itself a short synthetic **user** turn so its first message reflects what's selected:\n\n- **A concept node selected:** opens on that concept and one of its relations.\n- **An edge selected (no node):** opens on the typed relation between its endpoints.\n- **Nothing selected:** opens on a weak spot in the graph (low stability plus weak **last reviews** (Again/Hard or a long gap); **DUE** is extra scheduler context).\n\nClick **New chat** in the header to reset history and request a fresh opener.\n\n## Context size\n\nLarge graphs are summarised, not truncated abruptly. The weakest-reviewed nodes appear first (`nodeStrength`), so the verbatim slice emphasises instability and risky last ratings; tail nodes are omitted with a short count only. Edges have a ~2x allowance over node count. These limits live in [`MentorPanel.tsx`](https://github.com/nesso-how/nesso/blob/main/src/components/mentor/MentorPanel.tsx) as `MAX_SNAPSHOT_NODES` and `MAX_SNAPSHOT_EDGES`.\n\n## Privacy\n\n- **Local Ollama:** prompts and responses go only to your own machine; nothing leaves the device.\n- **Hosted endpoint:** the system prompt (graph snapshot) and chat history are sent to whichever endpoint you configured, each turn. The usual provider-side logging applies.\n\nYour graph itself always stays on your device regardless of the endpoint."
|
|
8
8
|
},
|
|
9
9
|
{
|
|
10
10
|
"slug": "guides/concepts-and-inspector",
|
|
11
11
|
"title": "Concepts & Inspector",
|
|
12
12
|
"description": "Adding concepts, drawing typed relations, and using the Inspector to enrich nodes with definitions, examples, notes, and images.",
|
|
13
|
-
"markdown": "The canvas is the centre of Nesso. **Concepts** are nodes; **typed relations** are edges. The **Inspector** is the right-hand panel where you enrich whatever you've got selected.\n\n## Adding concepts\n\n- **Double-click** empty canvas to add a concept at the pointer.\n- **`N`** adds a concept at the viewport centre.\n- **Right-click** empty canvas and choose **Add concept here** to add one at the cursor.\n- New concepts open in edit mode. Type the label and press `Enter` to commit, `Esc` to cancel.\n- **Double-click** a concept to rename it inline.\n\nAn empty graph shows a centered **\"Your first concept\"** hint; the double-click still works through it.\n\nConcepts you add are stored locally in IndexedDB. Switch graphs from the sidebar; create new graphs from the **Graphs** list.\n\n## Drawing relations\n\nDrag from a node's right edge (`out` handle) to another node's left edge (`in` handle). On release, a **relation picker** opens, grouped by category. Pick the relation type and the edge is created.\n\n- Drag-to-self is ignored, so you can't accidentally create self-loops.\n- The connection line previews with the same quadratic geometry the final edge uses.\n- Edge type can be changed any time from the Inspector when an edge is selected.\n\nSee the [relation types reference](../../reference/relation-types/) for the full list, semantic meaning, and coefficients. Per-type line style and glyph come from `@nesso-how/
|
|
13
|
+
"markdown": "The canvas is the centre of Nesso. **Concepts** are nodes; **typed relations** are edges. The **Inspector** is the right-hand panel where you enrich whatever you've got selected.\n\n## Adding concepts\n\n- **Double-click** empty canvas to add a concept at the pointer.\n- **`N`** adds a concept at the viewport centre.\n- **Right-click** empty canvas and choose **Add concept here** to add one at the cursor.\n- New concepts open in edit mode. Type the label and press `Enter` to commit, `Esc` to cancel.\n- **Double-click** a concept to rename it inline.\n\nAn empty graph shows a centered **\"Your first concept\"** hint; the double-click still works through it.\n\nConcepts you add are stored locally in IndexedDB. Switch graphs from the sidebar; create new graphs from the **Graphs** list.\n\n## Drawing relations\n\nDrag from a node's right edge (`out` handle) to another node's left edge (`in` handle). On release, a **relation picker** opens, grouped by category. Pick the relation type and the edge is created.\n\n- Drag-to-self is ignored, so you can't accidentally create self-loops.\n- The connection line previews with the same quadratic geometry the final edge uses.\n- Edge type can be changed any time from the Inspector when an edge is selected.\n\nSee the [relation types reference](../../reference/relation-types/) for the full list, semantic meaning, and coefficients. Per-type line style and glyph come from `@nesso-how/vocab-learning`; edge encoding density is under [Display options](#display-options-sidebar) below.\n\n## Selecting and editing\n\n- **Click** a node or edge to select it. The Inspector reflects the selection.\n- **Hold `⌘` / `Ctrl` and click** to toggle additional items into the selection.\n- **Drag on empty canvas** to marquee-select multiple items.\n- **`⌘A` / `Ctrl+A`** selects every concept and relation in the graph.\n- **Right-click** a concept, relation, or empty canvas for a context menu of the relevant actions (copy/cut/duplicate/delete a concept; flip / delete a relation; paste / add concept / center·fit on the canvas). To change a relation's type, select the edge and pick a new type in the Inspector.\n- **`Del`** or **`Backspace`** deletes the selection (one relation, one concept, or every concept in a marquee). Edges attached to a deleted concept go with it. Delete is also on the right-click menu and the Inspector's action toolbar.\n- **`⌘C` / `Ctrl+C`** copies the selection. Copying concepts also copies relations between them; copying a relation includes its two endpoints. **`⌘X` / `Ctrl+X`** cuts: it copies the selection and removes it in one step. **`⌘V` / `Ctrl+V`** pastes the clipboard with a small offset (right-click **Paste** drops it at the cursor instead). **`⌘D` / `Ctrl+D`** duplicates the selection in place without touching the clipboard. These also live on the right-click menu and the Inspector toolbar.\n- **Arrow keys** nudge a selected concept; **Shift + arrows** move it in larger steps.\n- **`⌘Z` / `Ctrl+Z`** undoes structural edits; **`⌘⇧Z` / `Ctrl+Shift+Z`** redoes. History has 50 steps and resets when you switch or import a graph.\n\n## The Inspector\n\nThe Inspector docks on the **right**, full height between the top bar and the status bar. Its header has a **collapse** control that shrinks it to a slim **rail** (keeping the selection plus a vertical action toolbar) and a **close** control; a docked bottom **action toolbar** offers copy / cut / duplicate / delete for a concept, or flip / delete for a relation.\n\nWhen a concept is selected it shows, top to bottom:\n\n- **Image + title:** the title edits inline (`Enter` commits, `Esc` reverts); the image button opens Commons search (see below).\n- **Memory** _(collapsible):_ the FSRS schedule, read-only — when due, stability (in days), last self-rating, review count (with lapses), and time since the last review.\n- **Definition**, **Examples**, **Notes** — see below.\n- **Relations** _(collapsible):_ outgoing and incoming edges, each connected concept shown with the relation glyph in a chip and the type on the right (incoming dimmed). Click a row to jump to that concept; change a relation's type by selecting the edge.\n\n### Notes fields\n\nThree free-text fields that travel with the concept and feed both the AI mentor and [Review](./review-mode/):\n\n- **Definition:** a one-sentence-ish explanation in your own words.\n- **Examples:** one per line. Press `Shift+Enter` or use the **Add** button to add a new line; press `Backspace` in an empty example to remove that line (unless it's the only one).\n- **Notes:** anything else: caveats, sources, mnemonics.\n\nIn Review, definition and examples appear when you **Reveal** a card so you can check your recall. The AI mentor uses the same fields in its graph snapshot and focal-neighbour context when a concept is selected.\n\n### Concept image\n\nPress the picture icon to open the **Wikimedia Commons search**. The query auto-fills from the concept title and runs immediately; pick any result to attach a 200-px thumbnail to the concept. The image shows in the Inspector, on reveal in Review mode, and is included as context for the AI mentor.\n\nThe image link and Commons description URL are persisted with the graph, so attribution is preserved on export.\n\n## Display options (sidebar)\n\n**Sidebar → Display** controls how the **active graph** is rendered: heatmap overlay, edge encoding density, curve style, and auto flip. Choices are saved **with the graph** in IndexedDB (and included in JSON export). New graphs start from the app defaults until you change them.\n\nWhen **Display → Curve** is set to **Arc**, **Auto flip** (on by default) bends relations toward the side that avoids overlapping nodes, flipping when the target is above the source on the right, or below on the left, and updates live while you drag concepts. **Flip curve** in the Inspector is **Off | Auto | On** while auto flip is on: **Auto** follows layout, **Off** / **On** pin a manual bend on that edge. With auto flip off for that graph, the control is **Off | On** only.\n\n## When an edge is selected\n\nThe Inspector shows the relation as a chip with its category colour and a dropdown of every relation type. Picking a new type updates the edge in place; the graph keeps its endpoints and identity.\n\n## Status bar and search\n\n- The **status bar** along the bottom shows the concept and relation counts. Its right side carries undo / redo, zoom out / in, and center·fit; the **Socrates** entry sits on the left.\n- **`⌘K` / `Ctrl+K`** opens a fuzzy search palette over concept titles. `Enter` selects and recenters the viewport; `Esc` closes.\n\n## Edge encoding density\n\nEdges carry three visual channels: colour (category), line style, and glyph. Crank this down for large or printed graphs from **Sidebar → Display → Edges**:\n\n- **Full:** colour + style + glyph (default).\n- **Category:** colour only.\n- **Minimal:** plain line, no encoding.\n\nSymmetric relations (similarity, opposition) never render an arrowhead regardless of encoding."
|
|
14
14
|
},
|
|
15
15
|
{
|
|
16
16
|
"slug": "guides/embedding-graphs",
|
|
@@ -33,8 +33,8 @@
|
|
|
33
33
|
{
|
|
34
34
|
"slug": "guides/review-mode",
|
|
35
35
|
"title": "Review mode",
|
|
36
|
-
"description": "Spaced-repetition review of your concepts with FSRS, how it queues cards
|
|
37
|
-
"markdown": "Press `R` (or open the **Review** pill in the top bar) to start a focused study session. Review surfaces concepts whose **FSRS** state says they are due,
|
|
36
|
+
"description": "Spaced-repetition review of your concepts with FSRS, how it queues cards and reschedules them from your self-ratings.",
|
|
37
|
+
"markdown": "Press `R` (or open the **Review** pill in the top bar) to start a focused study session. Review surfaces concepts whose **FSRS** state says they 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, examples, and typed relations before revealing.\n2. **Waits for you to think**, then click **Reveal** (or press `Space`).\n3. **Reveals** the concept's typed relations, examples, and image (the same panel you see in the Inspector).\n4. **You rate** how it felt: `Again`, `Hard`, `Good`, `Easy`. Each button shows the **predicted next interval** under it (e.g. `< 1d`, `4d`, `2mo`).\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| **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.\n\n## Keyboard shortcuts\n\n| Key | Action |\n| ----------------- | ------------ |\n| `Space` / `Enter` | Reveal |\n| `1` | Again |\n| `2` | Hard |\n| `3` | Good |\n| `4` | Easy |\n| `Esc` | Close review |\n\nNumeric keys only fire after the answer is revealed.\n\n## Tips\n\n- Add a **definition** and **examples** in the Inspector's Notes tab. They appear on reveal and give 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."
|
|
38
38
|
},
|
|
39
39
|
{
|
|
40
40
|
"slug": "introduction",
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import * as z from 'zod/v4';
|
|
2
|
-
import { RELATION_TYPES, RELATION_CATEGORY_META } from '@nesso-how/
|
|
2
|
+
import { RELATION_TYPES, RELATION_CATEGORY_META } from '@nesso-how/vocab-learning';
|
|
3
3
|
export function registerGetRelationTypes(server) {
|
|
4
4
|
server.registerTool('get_relation_types', {
|
|
5
5
|
description: 'Returns all 52 semantic relation types supported by Nesso, grouped by 8 categories. ' +
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nesso-how/mcp",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
3
|
+
"version": "0.1.0-alpha.34",
|
|
4
4
|
"description": "MCP server exposing Nesso knowledge graph tools to LLM clients",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
"dependencies": {
|
|
23
23
|
"zod": "^4.4.3",
|
|
24
24
|
"@modelcontextprotocol/server": "^2.0.0-alpha.2",
|
|
25
|
-
"@nesso-how/
|
|
25
|
+
"@nesso-how/vocab-learning": "0.1.0-alpha.34"
|
|
26
26
|
},
|
|
27
27
|
"devDependencies": {
|
|
28
28
|
"@types/node": "^22.0.0",
|