@nataliapc/mcp-openmsx 1.2.10 → 1.2.12

package/dist/vectordb.js

@@ -1,16 +1,53 @@
 /**
- * Vector Database wrapper class
+ * Vector Database wrapper class.
+ *
+ * Hybrid search over the MSX documentation corpus:
+ *   - dense vector search (cosine over 384-d embeddings, see embedder.ts)
+ *   - full-text search (BM25, LanceDB native FTS index)
+ *   - fused with Reciprocal Rank Fusion (RRF)
+ *
+ * Storage: LanceDB (columnar `.lance` table), replacing the previous Vectra
+ * `index.json`.
  *
  * @author Natalia Pujol Cremades (@nataliapc)
  * @license GPL2
  */
 import path from 'path';
-import { LocalIndex } from 'vectra';
-import embeddings from '@themaximalist/embeddings.js';
+import { pathToFileURL } from 'url';
+import * as lancedb from '@lancedb/lancedb';
+import { embedQuery } from './embedder.js';
+const TABLE_NAME = 'msxdocs';
+const TOP_K = 10; // final results returned
+const CANDIDATES = 30; // candidates fetched per branch before fusion
+const RRF_K = 60; // RRF constant
+/**
+ * Fuse two ranked result lists with Reciprocal Rank Fusion.
+ * Each document scores Σ 1/(k + rank) over the lists it appears in
+ * (rank is 0-based, so the +1 makes the top item contribute 1/(k+1)).
+ */
+export function fuseRRF(vecRows, ftsRows, k = RRF_K, topK = TOP_K) {
+    const acc = new Map();
+    const add = (rows) => {
+        rows.forEach((row, rank) => {
+            const id = String(row.id);
+            const inc = 1 / (k + rank + 1);
+            const cur = acc.get(id);
+            if (cur) {
+                cur.score += inc;
+            }
+            else {
+                acc.set(id, { score: inc, row });
+            }
+        });
+    };
+    add(vecRows);
+    add(ftsRows);
+    return [...acc.values()].sort((a, b) => b.score - a.score).slice(0, topK);
+}
 export class VectorDB {
-    static instance;
+    static instance = null;
     static vectorDbDir = path.join('..', 'vector-db');
-    index;
+    tablePromise = null;
     static getInstance() {
         if (!VectorDB.instance) {
             VectorDB.instance = new VectorDB();
@@ -20,42 +57,64 @@ export class VectorDB {
     static setIndexDirectory(dbDir) {
         VectorDB.vectorDbDir = dbDir;
     }
-    constructor(dbDir = VectorDB.vectorDbDir) {
-        this.index = new LocalIndex(dbDir);
-        if (!this.initDatabase()) {
-            throw new Error('Failed to initialize VectorDB: Index does not exist');
-        }
+    /**
+     * Resolve the directory into a value LanceDB can open.
+     *
+     * On Windows, LanceDB 0.30 (lance-io 7.0) mishandles drive-letter paths: it
+     * builds a malformed `file://` URL that drops the drive
+     * (`file:///mcp-server/vector-db/...`) and then fails to convert it back to a
+     * filesystem path. Passing an explicit, well-formed `file://` URI built by Node
+     * (`file:///M:/mcp-server/vector-db`) bypasses that broken path→URL step. On
+     * POSIX a plain path works fine, so we leave it untouched.
+     */
+    static resolveUri(dir) {
+        return process.platform === 'win32'
+            ? pathToFileURL(path.resolve(dir)).href
+            : dir;
     }
-    async initDatabase() {
-        return await this.index.isIndexCreated();
-    }
-    async getVector(text) {
-        const response = await embeddings(text);
-        if (!response || !Array.isArray(response) || response.length === 0) {
-            throw new Error('Failed to generate embedding vector');
+    getTable() {
+        if (!this.tablePromise) {
+            this.tablePromise = (async () => {
+                const db = await lancedb.connect(VectorDB.resolveUri(VectorDB.vectorDbDir));
+                return db.openTable(TABLE_NAME);
+            })().catch((err) => {
+                this.tablePromise = null;
+                throw new Error(`Failed to open LanceDB table '${TABLE_NAME}' at '${VectorDB.vectorDbDir}'. ` +
+                    `Has the index been generated? (${err instanceof Error ? err.message : err})`);
+            });
         }
-        return response;
+        return this.tablePromise;
     }
     async query(text) {
-        const vector = await this.getVector(text);
-        let results = [];
+        const tbl = await this.getTable();
+        const vector = await embedQuery(text);
+        // Vector branch (always available). No `.select()`: scoring queries warn
+        // when output columns are projected without `_distance`/`_score`, and the
+        // candidate set is tiny so fetching full rows is negligible.
+        const vecRows = await tbl
+            .query()
+            .nearestTo(vector)
+            .limit(CANDIDATES)
+            .toArray();
+        // Full-text (BM25) branch. Degrade gracefully to vector-only if the FTS
+        // index is missing or the query cannot be parsed.
+        let ftsRows = [];
         try {
-            results = await this.index.queryItems(vector, text, 10);
-            if (results.length > 0) {
-                return results.map(result => {
-                    return {
-                        score: result.score.toFixed(4),
-                        uri: result.item.metadata?.uri || 'unknown',
-                        title: result.item.metadata?.title || 'unknown',
-                        document: String(result.item.metadata?.document || ''),
-                        id: result.item.metadata?.id || 'unknown',
-                    };
-                });
-            }
+            ftsRows = await tbl
+                .query()
+                .nearestToText(text)
+                .limit(CANDIDATES)
+                .toArray();
         }
-        catch (error) {
-            throw new Error(`Query failed: ${error}`);
+        catch {
+            ftsRows = [];
         }
-        return results;
+        return fuseRRF(vecRows, ftsRows).map((r) => ({
+            score: r.score.toFixed(4),
+            uri: r.row.uri ?? 'unknown',
+            title: r.row.title ?? 'unknown',
+            document: String(r.row.text ?? ''),
+            id: r.row.id ?? 'unknown',
+        }));
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nataliapc/mcp-openmsx",
-  "version": "1.2.10",
+  "version": "1.2.12",
   "description": "Model context protocol server for openMSX automation and control",
   "main": "dist/server.js",
   "type": "module",
@@ -45,22 +45,18 @@
   "optionalDependencies": {
     "node-expose-sspi": "^0.1.60"
   },
-  "overrides": {
-    "sharp": "^0.34.5"
-  },
   "dependencies": {
+    "@anush008/tokenizers": "^0.6.0",
+    "@lancedb/lancedb": "^0.30.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@themaximalist/embeddings.js": "^0.1.3",
     "@types/express": "^5.0.6",
     "@types/mime-types": "^3.0.1",
-    "@xenova/transformers": "^2.17.2",
     "debug": "^4.4.3",
     "express": "^5.2.1",
     "mime-types": "^3.0.2",
+    "onnxruntime-node": "^1.27.0",
     "sanitize-html": "^2.17.4",
-    "sharp": "^0.34.5",
     "tsx": "^4.22.0",
-    "vectra": "^0.11.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {

package/resources/audio/chipsfmpacpr1_en.md

@@ -0,0 +1,209 @@
+# FM-PAC / MSX-MUSIC (Yamaha YM-2413)
+
+In this text, only the direct programming of the MSX-MUSIC will be discussed, not the FM-BASIC possibilities, because they finally use direct control.
+
+The MSX-MUSIC or the FM-PAC uses two I/O ports for control. Unfortunately, these registers are only used to write from the computer to the FM-PAC, so reading registers from the FM-PAC/MSX-MUSIC is not possible.
+
+```
+  07Ch           - Address port.
+  07Dh           - Data Port.
+```
+
+To control these ports correctly in machine language, it is useful to use the following program:
+
+```
+  ;Reg. D contains register number for FM-PAC.
+  ;Reg. E contains data for selected register.
+
+  SET_FM: LD   A,D
+          OUT  (07CH),A
+          LD   A,E
+          OUT  (07DH),A
+          EX   (SP),HL     ;These 2 commands only serve as a short
+          EX   (SP),HL     ;pause for the PAC to process the data
+          RET              ;before sending new data.
+```
+
+## Registers
+
+The FM-PAC contains 43 programmable registers for setting frequency, volume, instruments, drums and possibly samples. The latter is rather difficult, since the FM-PAC has no built-in hardware to play this independently like the MUSIC MODULE, a routine must be written in ML code for this, which sends the sample data in the FM-PAC via the necessary registers. so that it puts this sample on the sound output.
+
+```
+  #0Fh            FM.TST
+
+    7   6   5   4   3   2   1   0
+  ┌───┬───┬───┬───┬───┬───┬───┬───┐
+  │ - │ - │ - │ - │SND│ - │ - │SMP│
+  └───┴───┴───┴───┴───┴───┴───┴───┘
+
+SND  - 1=Sound output of the chip is out.
+SAMP - 1=Sample mode on, a four bit sample can be written to register
+         #10h, the 4 highest bit.
+```
+
+```
+  #10h - #18h     LOWFRQ
+
+    7   6   5   4   3   2   1   0
+  ┌───┬───┬───┬───┬───┬───┬───┬───┐
+  │FQ7│FQ6│FQ5│FQ4│FQ3│FQ2│FQ1│FQ0│
+  └───┴───┴───┴───┴───┴───┴───┴───┘
+```
+
+```
+  #20h - #28h     SELECT
+
+    7   6   5   4   3   2   1   0
+  ┌───┬───┬───┬───┬───┬───┬───┬───┐
+  │ - │ - │SUS│KEY│OC2│OC1│OC0│FQ8│
+  └───┴───┴───┴───┴───┴───┴───┴───┘
+
+FQ 8/0  - Frequency from channel 1 to 9.
+OC 2/0  - Octave from channel 1 to 9.
+KEY     - If a new tone has to be  struck it must  first be set to 0.
+          Then the new data can be  loaded (Frequency, Instrument and
+          volume), then set this bit back to 1.
+SUS     - If this bit is set to 1, the  tone  will slowly  fade after 
+          the KEY bit is set to 0. If SUS is at 0, the tone will stop
+          immediately when the KEY bit is turned off.
+```
+
+```
+  #30h - #38h     VOLINS
+
+    7   6   5   4   3   2   1   0
+  ┌───┬───┬───┬───┬───┬───┬───┬───┐
+  │IN3│IN2│IN1│IN0│VL3│VL2│VL1│VL0│
+  └───┴───┴───┴───┴───┴───┴───┴───┘
+
+VL 3/0  - Volume  from  channel 1 to 9. At  binary  0000  the  highest
+          volume is reached.
+IN 3/0  - Instruments from channels 1 to 9. There  are 16 instruments,
+          instrument number 0 of which can be programmed via registers
+          #00 to #07.
+
+  NR:   Instrument:
+
+  00    Software Instrument
+  01    Violin
+  02    Guitar
+  03    Piano
+  04    Flute
+  05    Clarinet
+  06    Oboe
+  07    Trumpet
+  08    Organ
+  09    Tube
+  10    Synthesizer
+  11    Harpsicord
+  12    Vibraphone
+  13    Synthesizer Bass
+  14    Electric Piano 1
+  15    Electric Piano 2
+```
+
+```
+  #03h            DRMSEL
+
+    7   6   5   4   3   2   1   0
+  ┌───┬───┬───┬───┬───┬───┬───┬───┐
+  │ - │ - │SEL│BD │SD │TOM│CIM│HH │
+  └───┴───┴───┴───┴───┴───┴───┴───┘
+
+SEL   - If  this  is  bit 1, channels 7 to 9 will  be  used  for  drum
+        settings, and bits 4 to 0 can be used to control a drum.
+BD    - Bass Drum :1 = Activate, if SEL is set to 1.
+SD    - Snare Drum.
+TOM   - Tom-Tom.
+CIM   - Cimbal.
+HH    - Hi Hat.
+```
+
+The Drum's frequencies and volumes are divided as follows:
+
+```
+Reg:  Use:
+#16h  Frequency bit 7 to 0 for the BassDrum.
+#17h  Frequency bit 7 to 0 for the SnareDrum and the HiHat.
+#18h  Frequency bit 7 to 0 for the TomTom and the Cimbal.
+#26h  Octave bit 2 to 0 and Frequency bit 8 for BassDrum.
+#27h  Octave bit 2 to 0 and Frequency bit 8 for SnareDrum & the HiHat.
+#28h  Octave bit 2 to 0 and Frequency bit 8 for Tom-Tom & the Cimbal.
+#36h  Low nibble is volume of Bass Drum (0 is the highest volume).
+#37h  High nibble is volume from Hi Hat.
+      Low nibble is volume from Snare Drum.
+#38h  High nibble is volume from Cimbal.
+      Low nibble is volume from Tom-Tom.
+```
+
+## Programming the Software Instrument.
+
+The FM contains 2 operators for each instrument. The sound is generated via the FM synthesis, which stands for Frequency Modulation. The System works the same as that of the Music-module/MSX-Audio only the maximum values will not always match, but the theory is the same.
+
+```
+  #00h/01h        SET.B / SET.A.
+
+    7   6   5   4   3   2   1   0
+  ┌───┬───┬───┬───┬───┬───┬───┬───┐
+  │ AM│VBR│S/D│RKS│MS3│MS2│MS1│MS0│
+  └───┴───┴───┴───┴───┴───┴───┴───┘
+
+  #00h for operator B and # 01h for operator A.
+
+  AM      - Amplitude Modulation.
+  VBR     - Vibrato.
+  S/D     - 0 = Decay; 1 = Sustain.
+  RKS     - Rate Key Scale.
+  MS3/0   - Multi sample wave selection.
+```
+
+```
+  #02h            KSCMOD
+
+    7   6   5   4   3   2   1   0
+  ┌───┬───┬───┬───┬───┬───┬───┬───┐
+  │LK1│LK0│MD5│MD4│MD3│MD2│MD1│MD0│
+  └───┴───┴───┴───┴───┴───┴───┴───┘
+
+  LK1/0   - Level Key Scale.
+  MD5/0   - Modulation Control.
+```
+
+```
+  #03h            FEED
+
+    7   6   5   4   3   2   1   0
+  ┌───┬───┬───┬───┬───┬───┬───┬───┐
+  │LK1│LK0│ - │DS2│DS1│FD2│FD1│FD0│
+  └───┴───┴───┴───┴───┴───┴───┴───┘
+
+  LK1/0   - Level Key Scale.
+  DS2/1   - Distorted Wave Form.
+  FD2/0   - FM-Feedback constant.
+```
+
+```
+  #04h / #05h     CTRL.B / CTRL.A
+
+    7   6   5   4   3   2   1   0
+  ┌───┬───┬───┬───┬───┬───┬───┬───┐
+  │AT3│AT2│AT1│AT0│DC3│DC2│DC1│DC0│
+  └───┴───┴───┴───┴───┴───┴───┴───┘
+
+  AT3/0   - Attack envelope rate.
+  DC3/0   - Decay envelope rate.
+```
+
+```
+  #06h / #07h     IND.B / IND.A
+
+    7   6   5   4   3   2   1   0
+  ┌───┬───┬───┬───┬───┬───┬───┬───┐
+  │IN3│IN2│IN1│IN0│RL3│RL2│RL1│RL0│
+  └───┴───┴───┴───┴───┴───┴───┴───┘
+
+  IN3/0   - Indication Decay / Sustain level.
+  RL3/0   - Release envelope rate.
+```
+
+The FM synthesis is quite complicated, especially for the beginner it is just a matter of trying. Fortunately, there are quite a few music programs on the market that handle this themselves.

package/resources/audio/chipsfmpacpr2_en.md

@@ -0,0 +1,170 @@
+# MSX-MUSIC REGISTERS
+
+## WRITE ONLY
+
+The registers of the MSX-MUSIC system, as found in: FM-Pac, FM-Stereo-Pak, MSX2+ and TurboR computers, are controlled via ports &H7C and &H7D. The control works according to the same principle as with MSX-AUDIO and the PSG. The register is specified in 7C and the data in 7D. Unfortunately, these are Write Only ports, so they cannot be read.
+
+## SOUND SETTINGS
+
+The OPLL data (original instrument) is specified in registers 0-7. This data corresponds to the data you can retrieve in the SynthSaurus Sound Editor, so you can easily retrieve a homemade instrument and write those values to registers 0-7.
+
+The following is the structure of registers 0-7 (OPLL instr)
+
+```
+Reg.nr.    Bit:    Function:
+------------------------------------------------------------
+0,1        0-3     Multi sample waves/harmonic relations
+           4       Rate key scale
+           5       Latching/sprouting (1=Latch 0=Latch)
+           6       Vibration on/off (1=on 0=off)
+           7       Amplitude modulation (1=on 0=off)
+
+2          0-5     Modulation index
+           6-7     Level key scale
+
+3          0-2     FM recoil
+           3-4     Load-bearing and modulated waveform
+                   link (FM/AM)
+           6-7     Level key scale
+
+4,5        0-3     Decay change
+           4-7     Attack change (swelling)
+
+6,7        0-3     Opening the change control
+           4-7     Major of Attack/Decay
+------------------------------------------------------------
+```
+
+## INSTRUMENT CONTROL
+
+The registers printed below are for the instrument selection/frequency/octave/volume and the so-called Sustain.
+
+```
+Reg.nr.    Bit:    Function:
+------------------------------------------------------------
+&H10-&H18  0-7     Note frequency LSB (8 bits)
+
+&H20-&H28  0       Note frequency MSB (1 bit)
+           1-3     Octave nr. (0-7, 0=octave 1, 7=octave 8)
+           4       Key on/off (1=on, 0=off)
+           5       Sustain (hold, 1=on, 0=off)
+
+&H30-&H38  0-3     Volume (0=vol.15, F=vol.0 !)
+           4-7     Instrument select (0=original, <>0=FM
+                                       instrument)
+------------------------------------------------------------
+```
+
+## FM INSTRUMENTS
+
+The MSX-MUSIC system has 15 pre-programmed instruments that can be used independently of each other.
+
+```
+0 = Original (custom instrument, see SOUND SETTINGS)
+1 = Violin                   9 = Horn
+2 = Guitar                   A = Synthesizer
+3 = Piano                    B = Harpsichord
+4 = Flute                    C = Vibraphone
+5 = Clarinet                 D = Synthesizer Bass
+6 = Oboe                     E = ElectrPiano2/Acoust. Bass
+7 = Trumpet                  F = ElectrPiano1/ElectrGuitar
+8 = Organ
+```
+
+## RHYTHM
+
+Register &H0E contains the drum selection, however bit 5 must be written before a drum can be heard. The drums can also be slightly changed, but rather limited and a bit chaotic. Below is a table of the drum values that can be written in register &H0E:
+
+```
+bit 0 = HiHat                bit 3 = Snare drum/Field drum
+bit 1 = Cymbal               bit 4 = Bass drum
+bit 2 = TomTom               bit 5 = selector (1 = Rhythm, 0 = Instrument)
+```
+
+Of course, multiple drums can be controlled simultaneously.
+The rhythm sound is structured as follows:
+
+```
+Drum type:    Reg.   Bit:    Function:
+------------------------------------------------------------
+Bass drum     &H16   0-7     Frequency LSB (8 bits)
+              &H26   0       Frequency MSB (1 bit)
+                     1-3     Octave (0-7)
+              &H36   0-3     Volume Bass drum
+
+Snare &       &h17   0-7     Frequency LSB (8 bits)
+HiHat         &H27   0       Frequency MSB (1 bit)
+                     1-3     Octave (0-7)
+              &H37   0-3     Volume Snare
+                     4-7     Volume HiHat
+
+Cymbal &      &H18   0-7     Frequency LSB (8 bits)
+TomTom        &H28   0       Frequency MSB (1 bit)
+                     1-3     Octave (0-7)
+              &H38   0-3     Volume Cymbal
+                     4-7     Volume TomTom
+------------------------------------------------------------
+```
+
+## BASIC REGISTERS
+
+The registers of the MSX-MUSIC system are, under BASIC!, maintained from address &HF9C0 to &HF9C0+&H38. The settings of these registers are filled with the following values after the command CALL MUSIC:
+
+```
+                                  Reg.nr.        Value:
+------------------------------------------------------------
+Register pair 1:   Instruments    &H10-&H15      &H56
+                   Drums          &H16           &H20
+                                  &H17           &H50
+                                  &H18           &HC0
+
+Register pair 2:   Instruments    &H20-&H25      &H00
+                   Drums          &H26           &H05
+                                  &H27           &H05
+                                  &H28           &H01
+
+Register pair 3:   Instruments    &H30-&H35      &H30
+                   Drums          &H36           &H01
+                                  &H37           &H11
+                                  &H38           &H11
+------------------------------------------------------------
+```
+
+## USAGE
+
+When using this information in, for example, an interrupt-driven music piece, you must take the following things into account.
+
+1) When a new frequency is specified for an instrument, bit 4 of the corresponding register must first be switched off. To clarify: if a new frequency needs to be entered in channel 1, bit 4 of register &H10 must be cleared. After that the frequency is written, and finally bit 4 is set again (reg. &H10). For other channels a different register is used accordingly.
+
+2) When an instrument is played that 'fades out' (Release), a short delay is needed in machine code:
+
+```z80
+         LD   B,3    ;approximately 3!
+   LOOP: DJNZ LOOP
+```
+
+3) The note frequencies are:
+
+```
+   Note:     LSB       MSB (bit 0 of reg &H20-&H28)
+   ---------------------------------------------------------
+   C         &HAD      0
+   C#        &HB7      0
+   D         &HC2      0
+   D#        &HCD      0
+   E         &HD9      0
+   F         &HE6      0
+   F#        &HF4      0
+   G         &H03      1
+   G#        &H12      1
+   A         &H22      1
+   A#        &H34      1
+   B         &H46      1
+   ---------------------------------------------------------
+```
+
+With this information you should now be able to control the MSX-MUSIC system through these registers. Good luck!
+
+by R.M.
+
+(Just to be clear: I don't know who R.M. is, but it's not me! - RM-FCS)

package/resources/audio/toc.json

@@ -8,6 +8,18 @@
             "external_url": "https://www.msx.org/wiki/PSG_Registers",
             "description": "Complete reference for MSX PSG (Programmable Sound Generator) registers covering all 16 registers including frequency control, white noise control, voice and I/O port control, amplitude and volume control, envelope form and period control, and I/O parallel port registers. Includes BIOS routines WRTPSG, RDPSG, and GICINI for PSG access and initialization."
         },
+        {
+            "title": "FM-PAC / MSX-MUSIC (Yamaha YM-2413)",
+            "uri": "msxdocs://audio/chipsfmpacpr1_en",
+            "external_url": "https://gitlab.com/moltsxalats/learning-fusion-c-programs/-/raw/9e9c4a754657db095a39cfdfc5659756cc8797e3/chipsfmpacpr1_en.txt",
+            "description": "Direct programming guide for the Yamaha YM-2413 (FM-PAC/MSX-MUSIC) chip via I/O ports 07Ch/07Dh. Covers all 43 write-only registers including frequency, octave, key control, volume, instrument selection, drum channels, and software instrument programming via FM synthesis operators."
+        },
+        {
+            "title": "MSX-MUSIC Registers",
+            "uri": "msxdocs://audio/chipsfmpacpr2_en",
+            "external_url": "https://gitlab.com/moltsxalats/learning-fusion-c-programs/-/raw/9e9c4a754657db095a39cfdfc5659756cc8797e3/chipsfmpacpr2_en.txt",
+            "description": "Register reference for the MSX-MUSIC OPLL chip (FM-PAC, FM-Stereo-Pak, MSX2+, TurboR) accessed via write-only ports &H7C/&H7D. Details OPLL custom instrument registers 0–7, instrument/frequency/octave/volume control registers, 15 preset FM instruments, rhythm/drum register layout, BASIC register defaults, and note frequency tables."
+        },
         {
             "title": "Konami SCC Sound Chip",
             "uri": "msxdocs://audio/sound_cartridge_scc",