From 227b1b50dbfe0ee09ded5c7aad8835988af14ead Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jose=20Francisco=20=27Kiko=27=20Verd=C3=BA=20Gamb=C3=ADn?=
 <2096101+Kikobeats@users.noreply.github.com>
Date: Sun, 13 Sep 2026 10:10:20 +0200
Subject: [PATCH 1/2] fix(mcp): correct VS Code configuration guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

VS Code's native .vscode/mcp.json uses a top-level "servers" object and
requires "type": "stdio" per server; the README showed Claude/Cursor's
mcpServers shape, which VS Code does not read. Keep the Codex claim out
(it uses its own TOML config) and preserve the Cursor section. Adds
regression tests for both client examples.

Signed-off-by: Jose Francisco 'Kiko' Verdú Gambín <2096101+Kikobeats@users.noreply.github.com>
---
 packages/mcp/README.md                        | 22 ++++++++----------
 .../mcp/test/readme-client-config.test.js     | 23 +++++++++++++++++++
 2 files changed, 33 insertions(+), 12 deletions(-)
 create mode 100644 packages/mcp/test/readme-client-config.test.js

diff --git a/packages/mcp/README.md b/packages/mcp/README.md
index bc2de53..6c2c7da 100644
--- a/packages/mcp/README.md
+++ b/packages/mcp/README.md
@@ -60,14 +60,15 @@ Edit `~/Library/Application\ Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-### VS Code / Codex
+### VS Code
 
-Published package:
+Add the published package to `.vscode/mcp.json`:
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "microlink": {
+      "type": "stdio",
       "command": "npx",
       "args": ["-y", "@microlink/mcp"],
       "env": {
@@ -78,18 +79,15 @@ Published package:
 }
 ```
 
-Local repository:
+For a local repository checkout, replace the server command with:
 
 ```json
 {
-  "mcpServers": {
-    "microlink": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp/src/index.js"],
-      "env": {
-        "MICROLINK_API_KEY": "YOUR_MICROLINK_API_KEY"
-      }
-    }
+  "type": "stdio",
+  "command": "node",
+  "args": ["/absolute/path/to/mcp/src/index.js"],
+  "env": {
+    "MICROLINK_API_KEY": "YOUR_MICROLINK_API_KEY"
   }
 }
 ```
diff --git a/packages/mcp/test/readme-client-config.test.js b/packages/mcp/test/readme-client-config.test.js
new file mode 100644
index 0000000..005afe1
--- /dev/null
+++ b/packages/mcp/test/readme-client-config.test.js
@@ -0,0 +1,23 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+
+const readme = await readFile(new URL('../README.md', import.meta.url), 'utf8')
+
+function section (start, end) {
+  return readme.slice(readme.indexOf(start), readme.indexOf(end))
+}
+
+test('VS Code example uses its native MCP configuration shape', () => {
+  const vscode = section('### VS Code\n', '### Cursor\n')
+
+  assert.match(vscode, /\.vscode\/mcp\.json/)
+  assert.match(vscode, /"servers":/)
+  assert.match(vscode, /"type": "stdio"/)
+  assert.doesNotMatch(vscode, /"mcpServers":/)
+})
+
+test('Cursor example keeps the portable mcpServers shape', () => {
+  const cursor = section('### Cursor\n', '## Usage\n')
+  assert.match(cursor, /"mcpServers":/)
+})

From 30f87377c066f6a79b08aa2fe8f0b62fc58423ca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jose=20Francisco=20=27Kiko=27=20Verd=C3=BA=20Gamb=C3=ADn?=
 <2096101+Kikobeats@users.noreply.github.com>
Date: Sun, 13 Sep 2026 11:21:53 +0200
Subject: [PATCH 2/2] test(mcp): cover both VS Code examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Assert the published and local-checkout snippets separately so the local
example cannot silently lose its stdio type or command shape.

Signed-off-by: Jose Francisco 'Kiko' Verdú Gambín <2096101+Kikobeats@users.noreply.github.com>
---
 .../mcp/test/readme-client-config.test.js     | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/packages/mcp/test/readme-client-config.test.js b/packages/mcp/test/readme-client-config.test.js
index 005afe1..46751e8 100644
--- a/packages/mcp/test/readme-client-config.test.js
+++ b/packages/mcp/test/readme-client-config.test.js
@@ -8,13 +8,26 @@ function section (start, end) {
   return readme.slice(readme.indexOf(start), readme.indexOf(end))
 }
 
-test('VS Code example uses its native MCP configuration shape', () => {
+test('VS Code examples use its native MCP configuration shape', () => {
   const vscode = section('### VS Code\n', '### Cursor\n')
+  const published = section(
+    'Add the published package to `.vscode/mcp.json`:',
+    'For a local repository checkout'
+  )
+  const local = section('For a local repository checkout', '### Cursor\n')
 
   assert.match(vscode, /\.vscode\/mcp\.json/)
-  assert.match(vscode, /"servers":/)
-  assert.match(vscode, /"type": "stdio"/)
   assert.doesNotMatch(vscode, /"mcpServers":/)
+
+  assert.match(published, /"servers":/)
+  assert.match(published, /"type": "stdio"/)
+  assert.match(published, /"command": "npx"/)
+  assert.match(published, /"MICROLINK_API_KEY"/)
+
+  assert.match(local, /"type": "stdio"/)
+  assert.match(local, /"command": "node"/)
+  assert.match(local, /"args": \["\/absolute\/path\/to\/mcp\/src\/index\.js"\]/)
+  assert.match(local, /"MICROLINK_API_KEY"/)
 })
 
 test('Cursor example keeps the portable mcpServers shape', () => {