coach-partner-mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,125 +1,129 @@
-# Coach Partner MCP V1
-
-A governed MCP adapter over **Coach Partner Open API V1**.
-
-This package is an interface adapter, not a second business backend. It does not access CloudBase, repositories, Domain Commands, lesson ledgers or finance data directly. Every tool calls the existing `/v1` Open API and inherits its delegated Integration identity, tenant isolation, scopes, idempotency, audit and Domain rules.
-
-## One-command CodeBuddy setup
-
-Target public command after npm release:
-
-```powershell
-npx -y coach-partner-mcp setup --host codebuddy
-```
-
-Default behavior:
-
-1. installs Coach Partner MCP into **CodeBuddy user scope**, so it is available across CodeBuddy projects;
-2. preserves existing CodeBuddy MCP servers, including CloudBase or other tools;
-3. follows CodeBuddy user-scope config priority (`~/.codebuddy/.mcp.json` → `~/.codebuddy/mcp.json` → `~/.codebuddy.json`);
-4. supports CodeBuddy JSONC files, including comments and trailing commas;
-5. securely prompts once for the Coach Partner connection credential if Windows Credential Manager does not already contain it;
-6. stores the credential in Windows Credential Manager, never in `.mcp.json`;
-7. runs a read-only `/v1/me` connectivity check;
-8. configures CodeBuddy to launch the version-pinned npm package through stdio;
-9. forces the public CodeBuddy launcher into **read-only MCP mode**.
-
-Project-only install is also available:
-
-```powershell
-npx -y coach-partner-mcp setup --host codebuddy --scope project --project C:\path\to\project
-```
-
-After setup, reload CodeBuddy. The MCP server name is `coach-partner`.
-
-### Authorization note
-
-One-command installation and service authorization are separate concerns. V1 expects the coach to receive a Coach Partner Open API connection credential from the governed onboarding process. The installer asks for it through a secure Windows prompt and stores it locally in Windows Credential Manager.
-
-The public install command must not contain a shared Production credential.
-
-## CLI
-
-```text
-coach-partner-mcp setup --host codebuddy
-coach-partner-mcp doctor
-coach-partner-mcp serve
-```
-
-- `setup` configures CodeBuddy and securely stores/uses the connection credential.
-- `doctor` verifies the stored credential and Open API identity without exposing the credential.
-- `serve` starts the stdio MCP server used by CodeBuddy.
-
-## Current boundary
-
-- Transport: local stdio.
-- SDK: `@modelcontextprotocol/server` 2.3.1.
-- Public CodeBuddy installer: Windows V1.
-- Default/public CodeBuddy tool surface: read-only.
-- Public `serve` command forcibly disables classroom writes and session actions.
-- Write-capable MCP exposure remains a separately governed path and is not enabled by the one-command installer.
-- Payment/refund/finance mutation is not exposed.
-
-## Tools
-
-Read-only default (9):
-
-- `get_identity`
-- `list_classes`
-- `find_sessions`
-- `get_session`
-- `get_session_roster`
-- `get_learner`
-- `get_learner_measurements`
-- `get_lesson_account`
-- `list_metrics`
-
-The underlying MCP adapter still contains governed classroom-write tools for controlled internal configurations, but the public CodeBuddy `serve` launcher does not expose them.
-
-## Security rules
-
-- non-loopback base URLs must use HTTPS;
-- base URL credentials/query/fragment/path are rejected;
-- the connection credential is never written to CodeBuddy MCP configuration;
-- the connection credential is never logged or returned by an MCP tool;
-- Windows installation stores the credential in Windows Credential Manager;
-- existing CodeBuddy MCP configuration is updated atomically and other MCP servers are preserved;
-- invalid config fails closed rather than overwriting user files;
-- Open API remains the final authorization authority;
-- public CodeBuddy setup is read-only even if unrelated environment variables request write exposure.
-
-## Local development
-
-```powershell
-cd mcp\coach-partner
-npm install
-npm run check
-npm run pack:check
-```
-
-`npm run check` performs syntax validation plus unit, config, JSONC, MCP protocol, Open API client and real stdio child-process smoke tests.
-
-Before the npm package is publicly released, local dogfood can use:
-
-```powershell
-npx -y file:. doctor
-npx -y file:. setup --host codebuddy --package-spec file:C:\absolute\path\to\mcp\coach-partner
-```
-
-## Distribution gate
-
-`coach-partner-mcp` is prepared as a public npm package, but publication is a separate release action. Verify package contents with:
-
-```powershell
-npm pack --dry-run
-```
-
-After npm authentication and publication, the stable external instruction becomes exactly:
-
-```powershell
-npx -y coach-partner-mcp setup --host codebuddy
-```
-
-## Non-goals
-
-No raw API/path tool, direct database access, OAuth, remote MCP HTTP hosting, finance/refund/payment mutation, direct lesson-balance mutation, generic Tool Gateway or multi-agent platform is included in V1.
+# Coach Partner MCP V1
+
+A governed MCP adapter over **Coach Partner Open API V1**.
+
+This package is an interface adapter, not a second business backend. It does not access CloudBase, repositories, Domain Commands, lesson ledgers or finance data directly. Every tool calls the existing `/v1` Open API and inherits its delegated Integration identity, tenant isolation, scopes, idempotency, audit and Domain rules.
+
+## One-command CodeBuddy setup
+
+Target public command after npm release:
+
+```powershell
+npx -y coach-partner-mcp setup --host codebuddy
+```
+
+Default behavior:
+
+1. installs Coach Partner MCP into **CodeBuddy user scope**, so it is available across CodeBuddy projects;
+2. preserves existing CodeBuddy MCP servers, including CloudBase or other tools;
+3. follows CodeBuddy user-scope config priority (`~/.codebuddy/.mcp.json` → `~/.codebuddy/mcp.json` → `~/.codebuddy.json`);
+4. supports CodeBuddy JSONC files, including comments and trailing commas;
+5. securely prompts once for the Coach Partner connection credential if Windows Credential Manager does not already contain it;
+6. stores the credential in Windows Credential Manager, never in `.mcp.json`;
+7. runs a read-only `/v1/me` connectivity check;
+8. configures CodeBuddy to launch the version-pinned npm package through stdio;
+9. forces the public CodeBuddy launcher into **read-only MCP mode**.
+
+Project-only install is also available:
+
+```powershell
+npx -y coach-partner-mcp setup --host codebuddy --scope project --project C:\path\to\project
+```
+
+After setup, reload CodeBuddy. The MCP server name is `coach-partner`.
+
+### Authorization note
+
+One-command installation and service authorization are separate concerns. V1 expects the coach to receive a Coach Partner Open API connection credential from the governed onboarding process. The installer asks for it through a secure Windows prompt and stores it locally in Windows Credential Manager.
+
+The public install command must not contain a shared Production credential.
+
+## CLI
+
+```text
+coach-partner-mcp setup --host codebuddy
+coach-partner-mcp doctor
+coach-partner-mcp serve
+```
+
+- `setup` configures CodeBuddy and securely stores/uses the connection credential.
+- `doctor` verifies the stored credential and Open API identity without exposing the credential.
+- `serve` starts the stdio MCP server used by CodeBuddy.
+
+## Current boundary
+
+- Transport: local stdio.
+- SDK: `@modelcontextprotocol/server` 2.3.1.
+- Public CodeBuddy installer: Windows V1.
+- Default/public CodeBuddy tool surface: read-only.
+- Public `serve` command forcibly disables classroom writes and session actions.
+- Write-capable MCP exposure remains a separately governed path and is not enabled by the one-command installer.
+- Payment/refund/finance mutation is not exposed.
+
+## Tools
+
+Read-only default (9):
+
+- `get_identity`
+- `list_classes`
+- `find_sessions`
+- `get_session`
+- `get_session_roster`
+- `get_learner`
+- `get_learner_measurements`
+- `get_lesson_account`
+- `list_metrics`
+
+The underlying MCP adapter still contains governed classroom-write tools for controlled internal configurations, but the public CodeBuddy `serve` launcher does not expose them.
+
+## Security rules
+
+- non-loopback base URLs must use HTTPS;
+- base URL credentials/query/fragment/path are rejected;
+- the connection credential is never written to CodeBuddy MCP configuration;
+- the connection credential is never logged or returned by an MCP tool;
+- Windows installation stores the credential in Windows Credential Manager;
+- existing CodeBuddy MCP configuration is updated atomically and other MCP servers are preserved;
+- invalid config fails closed rather than overwriting user files;
+- Open API remains the final authorization authority;
+- public CodeBuddy setup is read-only even if unrelated environment variables request write exposure.
+
+## Local development
+
+```powershell
+cd mcp\coach-partner
+npm install
+npm run check
+npm run pack:check
+```
+
+`npm run check` performs syntax validation plus unit, config, JSONC, MCP protocol, Open API client and real stdio child-process smoke tests.
+
+Before the npm package is publicly released, local dogfood can use:
+
+```powershell
+npx -y file:. doctor
+npx -y file:. setup --host codebuddy --package-spec file:C:\absolute\path\to\mcp\coach-partner
+```
+
+## Public distribution and release
+
+`coach-partner-mcp` is publicly distributed on npm. The stable external installation command is:
+
+```powershell
+npx -y coach-partner-mcp setup --host codebuddy
+```
+
+Release validation remains mandatory:
+
+```powershell
+npm ci
+npm run check
+npm pack --dry-run
+```
+
+Future releases use the dedicated GitHub Actions release lane and npm Trusted Publishing. CI receives short-lived OIDC authority to **stage** a package only; it does not store a long-lived npm publish token and does not directly make a candidate public. The release tag must be `coach-partner-mcp-v<package.json version>`. After GitHub Actions creates the npm staged candidate, the Founder verifies it and approves publication with npm Passkey/2FA. See `operations/runbooks/coach-partner-mcp-release.md`.
+
+## Non-goals
+
+No raw API/path tool, direct database access, OAuth, remote MCP HTTP hosting, finance/refund/payment mutation, direct lesson-balance mutation, generic Tool Gateway or multi-agent platform is included in V1.

package/package.json

@@ -1,33 +1,38 @@
-{
-  "name": "coach-partner-mcp",
-  "version": "0.1.0",
-  "type": "module",
-  "description": "Governed Coach Partner MCP adapter and one-command CodeBuddy installer.",
-  "license": "UNLICENSED",
-  "bin": {
-    "coach-partner-mcp": "src/cli.mjs"
-  },
-  "files": [
-    "src/",
-    "scripts/",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=20.19"
-  },
-  "scripts": {
-    "start": "node src/cli.mjs serve",
-    "test": "node --test",
-    "check:syntax": "node --check src/config.mjs && node --check src/open-api-client.mjs && node --check src/tools.mjs && node --check src/server-factory.mjs && node --check src/server.mjs && node --check src/codebuddy-setup.mjs && node --check src/windows-secure-store.mjs && node --check src/doctor.mjs && node --check src/cli.mjs",
-    "check": "npm run check:syntax && npm test",
-    "pack:check": "npm pack --dry-run"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/server": "2.3.1",
-    "jsonc-parser": "3.3.1",
-    "zod": "4.6.7"
-  },
-  "devDependencies": {
-    "@modelcontextprotocol/client": "2.3.1"
-  }
-}
+{
+  "name": "coach-partner-mcp",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Governed Coach Partner MCP adapter and one-command CodeBuddy installer.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nongjianweihao/coach-os-wechat.git",
+    "directory": "mcp/coach-partner"
+  },
+  "license": "UNLICENSED",
+  "bin": {
+    "coach-partner-mcp": "src/cli.mjs"
+  },
+  "files": [
+    "src/",
+    "scripts/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "scripts": {
+    "start": "node src/cli.mjs serve",
+    "test": "node --test",
+    "check:syntax": "node --check src/config.mjs && node --check src/open-api-client.mjs && node --check src/tools.mjs && node --check src/server-factory.mjs && node --check src/server.mjs && node --check src/codebuddy-setup.mjs && node --check src/windows-secure-store.mjs && node --check src/doctor.mjs && node --check src/cli.mjs",
+    "check": "npm run check:syntax && npm test",
+    "pack:check": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.3.1",
+    "jsonc-parser": "3.3.1",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.3.1"
+  }
+}

package/scripts/windows-secure-store.ps1

@@ -1,133 +1,133 @@
-[CmdletBinding()]
-param(
-  [Parameter(Mandatory=$true)]
-  [ValidateSet('Store','Status','Read')]
-  [string]$Action,
-  [Parameter(Mandatory=$true)]
-  [string]$TargetName
-)
-
-Set-StrictMode -Version Latest
-$ErrorActionPreference = 'Stop'
-
-if (-not ('CoachPartnerMcpSecureStoreNative' -as [type])) {
-  Add-Type -TypeDefinition @"
-using System;
-using System.Runtime.InteropServices;
-
-[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
-public struct CoachPartnerMcpNativeCredential {
-  public UInt32 Flags;
-  public UInt32 Type;
-  public string TargetName;
-  public string Comment;
-  public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
-  public UInt32 CredentialBlobSize;
-  public IntPtr CredentialBlob;
-  public UInt32 Persist;
-  public UInt32 AttributeCount;
-  public IntPtr Attributes;
-  public string TargetAlias;
-  public string UserName;
-}
-
-public static class CoachPartnerMcpSecureStoreNative {
-  [DllImport("advapi32.dll", EntryPoint = "CredWriteW", CharSet = CharSet.Unicode, SetLastError = true)]
-  public static extern bool CredWrite(ref CoachPartnerMcpNativeCredential credential, UInt32 flags);
-
-  [DllImport("advapi32.dll", EntryPoint = "CredReadW", CharSet = CharSet.Unicode, SetLastError = true)]
-  public static extern bool CredRead(string target, UInt32 type, UInt32 reservedFlag, out IntPtr credentialPtr);
-
-  [DllImport("advapi32.dll", SetLastError = true)]
-  public static extern void CredFree(IntPtr buffer);
-}
-"@
-}
-
-$CRED_TYPE_GENERIC = [uint32]1
-$CRED_PERSIST_LOCAL_MACHINE = [uint32]2
-
-function Get-NativeCredential {
-  $ptr = [IntPtr]::Zero
-  if (-not [CoachPartnerMcpSecureStoreNative]::CredRead($TargetName, $CRED_TYPE_GENERIC, 0, [ref]$ptr)) {
-    return $null
-  }
-  try {
-    $credential = [Runtime.InteropServices.Marshal]::PtrToStructure($ptr, [type][CoachPartnerMcpNativeCredential])
-    if ($credential.CredentialBlobSize -eq 0 -or $credential.CredentialBlob -eq [IntPtr]::Zero) {
-      return $null
-    }
-    $bytes = New-Object byte[] $credential.CredentialBlobSize
-    [Runtime.InteropServices.Marshal]::Copy($credential.CredentialBlob, $bytes, 0, $bytes.Length)
-    try {
-      return [Text.Encoding]::Unicode.GetString($bytes)
-    }
-    finally {
-      [Array]::Clear($bytes, 0, $bytes.Length)
-    }
-  }
-  finally {
-    if ($ptr -ne [IntPtr]::Zero) { [CoachPartnerMcpSecureStoreNative]::CredFree($ptr) }
-  }
-}
-
-function Store-NativeCredential {
-  $secure = Read-Host 'Coach Partner connection credential' -AsSecureString
-  $bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
-  try {
-    $plain = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr)
-    if ($plain -notmatch '^cp_v1_[a-f0-9]{32}\.[A-Za-z0-9_-]{32,128}$') {
-      throw 'Credential format is invalid.'
-    }
-    $bytes = [Text.Encoding]::Unicode.GetBytes($plain)
-    $blob = [Runtime.InteropServices.Marshal]::AllocHGlobal($bytes.Length)
-    try {
-      [Runtime.InteropServices.Marshal]::Copy($bytes, 0, $blob, $bytes.Length)
-      $credential = New-Object CoachPartnerMcpNativeCredential
-      $credential.Flags = 0
-      $credential.Type = $CRED_TYPE_GENERIC
-      $credential.TargetName = $TargetName
-      $credential.Comment = 'Coach Partner MCP connection credential. Managed by coach-partner-mcp setup.'
-      $credential.CredentialBlobSize = [uint32]$bytes.Length
-      $credential.CredentialBlob = $blob
-      $credential.Persist = $CRED_PERSIST_LOCAL_MACHINE
-      $credential.AttributeCount = 0
-      $credential.Attributes = [IntPtr]::Zero
-      $credential.TargetAlias = $null
-      $credential.UserName = 'CoachPartnerMcp'
-      if (-not [CoachPartnerMcpSecureStoreNative]::CredWrite([ref]$credential, 0)) {
-        $code = [Runtime.InteropServices.Marshal]::GetLastWin32Error()
-        throw "Credential Manager write failed: $(([ComponentModel.Win32Exception]::new($code)).Message)"
-      }
-    }
-    finally {
-      if ($blob -ne [IntPtr]::Zero) {
-        for ($i = 0; $i -lt $bytes.Length; $i++) { [Runtime.InteropServices.Marshal]::WriteByte($blob, $i, 0) }
-        [Runtime.InteropServices.Marshal]::FreeHGlobal($blob)
-      }
-      [Array]::Clear($bytes, 0, $bytes.Length)
-      $plain = $null
-    }
-  }
-  finally {
-    [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr)
-  }
-}
-
-switch ($Action) {
-  'Status' {
-    $value = Get-NativeCredential
-    if ($null -eq $value) { 'missing' } else { 'configured' }
-    $value = $null
-  }
-  'Read' {
-    $value = Get-NativeCredential
-    if ($null -eq $value) { throw 'Coach Partner connection credential is not configured.' }
-    [Console]::Out.Write($value)
-    $value = $null
-  }
-  'Store' {
-    Store-NativeCredential
-    'configured'
-  }
-}
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory=$true)]
+  [ValidateSet('Store','Status','Read')]
+  [string]$Action,
+  [Parameter(Mandatory=$true)]
+  [string]$TargetName
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+if (-not ('CoachPartnerMcpSecureStoreNative' -as [type])) {
+  Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+
+[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+public struct CoachPartnerMcpNativeCredential {
+  public UInt32 Flags;
+  public UInt32 Type;
+  public string TargetName;
+  public string Comment;
+  public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+  public UInt32 CredentialBlobSize;
+  public IntPtr CredentialBlob;
+  public UInt32 Persist;
+  public UInt32 AttributeCount;
+  public IntPtr Attributes;
+  public string TargetAlias;
+  public string UserName;
+}
+
+public static class CoachPartnerMcpSecureStoreNative {
+  [DllImport("advapi32.dll", EntryPoint = "CredWriteW", CharSet = CharSet.Unicode, SetLastError = true)]
+  public static extern bool CredWrite(ref CoachPartnerMcpNativeCredential credential, UInt32 flags);
+
+  [DllImport("advapi32.dll", EntryPoint = "CredReadW", CharSet = CharSet.Unicode, SetLastError = true)]
+  public static extern bool CredRead(string target, UInt32 type, UInt32 reservedFlag, out IntPtr credentialPtr);
+
+  [DllImport("advapi32.dll", SetLastError = true)]
+  public static extern void CredFree(IntPtr buffer);
+}
+"@
+}
+
+$CRED_TYPE_GENERIC = [uint32]1
+$CRED_PERSIST_LOCAL_MACHINE = [uint32]2
+
+function Get-NativeCredential {
+  $ptr = [IntPtr]::Zero
+  if (-not [CoachPartnerMcpSecureStoreNative]::CredRead($TargetName, $CRED_TYPE_GENERIC, 0, [ref]$ptr)) {
+    return $null
+  }
+  try {
+    $credential = [Runtime.InteropServices.Marshal]::PtrToStructure($ptr, [type][CoachPartnerMcpNativeCredential])
+    if ($credential.CredentialBlobSize -eq 0 -or $credential.CredentialBlob -eq [IntPtr]::Zero) {
+      return $null
+    }
+    $bytes = New-Object byte[] $credential.CredentialBlobSize
+    [Runtime.InteropServices.Marshal]::Copy($credential.CredentialBlob, $bytes, 0, $bytes.Length)
+    try {
+      return [Text.Encoding]::Unicode.GetString($bytes)
+    }
+    finally {
+      [Array]::Clear($bytes, 0, $bytes.Length)
+    }
+  }
+  finally {
+    if ($ptr -ne [IntPtr]::Zero) { [CoachPartnerMcpSecureStoreNative]::CredFree($ptr) }
+  }
+}
+
+function Store-NativeCredential {
+  $secure = Read-Host 'Coach Partner connection credential' -AsSecureString
+  $bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
+  try {
+    $plain = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr)
+    if ($plain -notmatch '^cp_v1_[a-f0-9]{32}\.[A-Za-z0-9_-]{32,128}$') {
+      throw 'Credential format is invalid.'
+    }
+    $bytes = [Text.Encoding]::Unicode.GetBytes($plain)
+    $blob = [Runtime.InteropServices.Marshal]::AllocHGlobal($bytes.Length)
+    try {
+      [Runtime.InteropServices.Marshal]::Copy($bytes, 0, $blob, $bytes.Length)
+      $credential = New-Object CoachPartnerMcpNativeCredential
+      $credential.Flags = 0
+      $credential.Type = $CRED_TYPE_GENERIC
+      $credential.TargetName = $TargetName
+      $credential.Comment = 'Coach Partner MCP connection credential. Managed by coach-partner-mcp setup.'
+      $credential.CredentialBlobSize = [uint32]$bytes.Length
+      $credential.CredentialBlob = $blob
+      $credential.Persist = $CRED_PERSIST_LOCAL_MACHINE
+      $credential.AttributeCount = 0
+      $credential.Attributes = [IntPtr]::Zero
+      $credential.TargetAlias = $null
+      $credential.UserName = 'CoachPartnerMcp'
+      if (-not [CoachPartnerMcpSecureStoreNative]::CredWrite([ref]$credential, 0)) {
+        $code = [Runtime.InteropServices.Marshal]::GetLastWin32Error()
+        throw "Credential Manager write failed: $(([ComponentModel.Win32Exception]::new($code)).Message)"
+      }
+    }
+    finally {
+      if ($blob -ne [IntPtr]::Zero) {
+        for ($i = 0; $i -lt $bytes.Length; $i++) { [Runtime.InteropServices.Marshal]::WriteByte($blob, $i, 0) }
+        [Runtime.InteropServices.Marshal]::FreeHGlobal($blob)
+      }
+      [Array]::Clear($bytes, 0, $bytes.Length)
+      $plain = $null
+    }
+  }
+  finally {
+    [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr)
+  }
+}
+
+switch ($Action) {
+  'Status' {
+    $value = Get-NativeCredential
+    if ($null -eq $value) { 'missing' } else { 'configured' }
+    $value = $null
+  }
+  'Read' {
+    $value = Get-NativeCredential
+    if ($null -eq $value) { throw 'Coach Partner connection credential is not configured.' }
+    [Console]::Out.Write($value)
+    $value = $null
+  }
+  'Store' {
+    Store-NativeCredential
+    'configured'
+  }
+}