Merge branch 'jahe-addAnnotateCLI' of https://github.com/hejingkan2005/mcp into jahe-addAnnotateCLI

# Conflicts:
#	cli/src/context.ts

Author: hejingkan2005

cli/src/commands/code-search.ts

@@ -19,11 +19,7 @@ export function registerCodeSearchCommand(program: Command, context: CliContext)
     .option('--json', 'Output raw JSON instead of formatted text.')
     .action(async (query: string, options: CodeSearchCommandOptions) => {
       const endpoint = resolveEndpoint(program.opts<{ endpoint?: string }>().endpoint, context.env);
-      const client = context.createClient({
-        endpoint,
-        clientName: 'mslearn',
-        clientVersion: context.version,
-      });
+      const client = context.createClient({ endpoint });
 
       try {
         const payload = await client.searchCodeSamples(query, options.language);

cli/src/commands/doctor.ts

@@ -35,17 +35,13 @@ export function registerDoctorCommand(program: Command, context: CliContext): vo
 async function runDoctorChecks(endpoint: string, context: CliContext): Promise<DoctorReport> {
   const runtimeVersion = process.versions.node;
   const runtimeSupported = Number.parseInt(runtimeVersion.split('.')[0] ?? '0', 10) >= 22;
-  const reachability = await probeEndpoint(endpoint, context.fetchImpl);
+  const reachability = await probeEndpoint(endpoint);
   const errors: string[] = [];
   const tools: DoctorReport['tools'] = {};
   let connected = false;
   let discovered = false;
 
-  const client = context.createClient({
-    endpoint,
-    clientName: 'mslearn',
-    clientVersion: context.version,
-  });
+  const client = context.createClient({ endpoint });
 
   try {
     const mapping = await client.getToolMapping(true);

cli/src/commands/fetch.ts

@@ -20,11 +20,7 @@ export function registerFetchCommand(program: Command, context: CliContext): voi
     .action(async (url: string, options: FetchCommandOptions) => {
       const endpoint = resolveEndpoint(program.opts<{ endpoint?: string }>().endpoint, context.env);
       const normalizedUrl = normalizeUrl(url);
-      const client = context.createClient({
-        endpoint,
-        clientName: 'mslearn',
-        clientVersion: context.version,
-      });
+      const client = context.createClient({ endpoint });
 
       try {
         const markdown = await client.fetchDocument(normalizedUrl);

cli/src/commands/search.ts

@@ -17,11 +17,7 @@ export function registerSearchCommand(program: Command, context: CliContext): vo
     .option('--json', 'Output raw JSON instead of formatted text.')
     .action(async (query: string, options: SearchCommandOptions) => {
       const endpoint = resolveEndpoint(program.opts<{ endpoint?: string }>().endpoint, context.env);
-      const client = context.createClient({
-        endpoint,
-        clientName: 'mslearn',
-        clientVersion: context.version,
-      });
+      const client = context.createClient({ endpoint });
 
       try {
         const payload = await client.searchDocs(query);

cli/src/context.ts

@@ -6,7 +6,6 @@ export interface CliContext {
   version: string;
   writeOut: (value: string) => void;
   writeErr: (value: string) => void;
-  fetchImpl: typeof fetch;
   createClient: (options: LearnClientOptions) => LearnCliClientLike;
   createAnnotationStore: () => AnnotationStore;
 }
@@ -22,7 +21,11 @@ export function createDefaultContext(version: string): CliContext {
       process.stderr.write(value);
     },
     fetchImpl: globalThis.fetch.bind(globalThis) as typeof fetch,
-    createClient: (options) => createLearnCliClient(options),
+    createClient: (options) =>
+      createLearnCliClient({
+        clientVersion: version,
+        ...options,
+      }),
     createAnnotationStore: () => createFileAnnotationStore(),
   };
 }

cli/src/index.ts

@@ -26,12 +26,8 @@ export function createProgram(context: CliContext): Command {
     .addOption(new Option('--endpoint <url>', 'Override the Learn MCP endpoint for this command.').hideHelp())
     .showHelpAfterError()
     .configureOutput({
-      writeOut: (value) => {
-        context.writeOut(value);
-      },
-      writeErr: (value) => {
-        context.writeErr(value);
-      },
+      writeOut: context.writeOut,
+      writeErr: context.writeErr,
       outputError: (value, write) => {
         write(value);
       },

cli/src/mcp/client.ts

@@ -7,6 +7,8 @@ import { OperationError } from '../utils/errors.js';
 import { createFileLearnSessionCacheStore, type LearnSessionCacheStore } from './cache.js';
 import { discoverLearnTools, type DiscoveredLearnTools, type ListedTool } from './tool-discovery.js';
 
+const DEFAULT_CLIENT_NAME = 'learn-cli';
+
 export interface LearnClientOptions {
   endpoint: string;
   clientName?: string;
@@ -43,7 +45,7 @@ interface TransportLike {
   close(): Promise<void>;
 }
 
-export async function probeEndpoint(endpoint: string, fetchImpl: typeof fetch): Promise<ReachabilityReport> {
+export async function probeEndpoint(endpoint: string, fetchImpl: typeof fetch = globalThis.fetch): Promise<ReachabilityReport> {
   try {
     const response = await fetchImpl(endpoint, {
       method: 'GET',
@@ -271,7 +273,7 @@ class LearnCliClient implements LearnCliClientLike {
   private createDefaultSdkClient(): SdkClientLike {
     return new Client(
       {
-        name: this.options.clientName ?? 'mslearn',
+        name: this.options.clientName ?? DEFAULT_CLIENT_NAME,
         version: this.options.clientVersion ?? '0.1.0',
       },
       {

cli/test/unit/cli.test.ts

@@ -43,7 +43,6 @@ function createTestContext(client: LearnCliClientLike): {
       writeErr: (value) => {
         stderr.push(value);
       },
-      fetchImpl: vi.fn(async () => new Response(null, { status: 405 })) as unknown as typeof fetch,
       createClient: () => client,
       createAnnotationStore: () => createFileAnnotationStore({ annotationsDir }),
     },

skills/microsoft-code-reference/SKILL.md

@@ -2,7 +2,7 @@
 name: microsoft-code-reference
 description: Look up Microsoft API references, find working code samples, and verify SDK code is correct. Use when working with Azure SDKs, .NET libraries, or Microsoft APIs—to find the right method, check parameters, get working examples, or troubleshoot errors. Catches hallucinated methods, wrong signatures, and deprecated patterns by querying official docs.
 context: fork
-compatibility: Requires Microsoft Learn MCP Server (https://learn.microsoft.com/api/mcp)
+compatibility: Works best with Microsoft Learn MCP Server (https://learn.microsoft.com/api/mcp). Can also use the mslearn CLI as a fallback.
 ---
 
 # Microsoft Code Reference
@@ -77,3 +77,24 @@ Before generating code using Microsoft SDKs, verify it's correct:
 3. **Find working sample** — `microsoft_code_sample_search(query: "[task]", language: "[lang]")`
 
 For simple lookups, step 1 alone may suffice. For complex API usage, complete all three steps.
+
+## CLI Alternative
+
+If the Learn MCP server is not available, use the `mslearn` CLI from the command line instead:
+
+```sh
+# Run directly (no install needed)
+npx @microsoft/learn-cli search "BlobClient UploadAsync Azure.Storage.Blobs"
+
+# Or install globally, then run
+npm install -g @microsoft/learn-cli
+mslearn search "BlobClient UploadAsync Azure.Storage.Blobs"
+```
+
+| MCP Tool | CLI Command |
+|----------|-------------|
+| `microsoft_docs_search(query: "...")` | `mslearn search "..."` |
+| `microsoft_code_sample_search(query: "...", language: "...")` | `mslearn code-search "..." --language ...` |
+| `microsoft_docs_fetch(url: "...")` | `mslearn fetch "..."` |
+
+Pass `--json` to `search` or `code-search` to get raw JSON output for further processing.

skills/microsoft-docs/SKILL.md

@@ -2,7 +2,7 @@
 name: microsoft-docs
 description: Query official Microsoft documentation to understand concepts, find tutorials, and learn how services work. Use for Azure, .NET, Microsoft 365, Windows, Power Platform, and all Microsoft technologies. Get accurate, current information from learn.microsoft.com and other official Microsoft websites—architecture overviews, quickstarts, configuration guides, limits, and best practices.
 context: fork
-compatibility: Requires Microsoft Learn MCP Server (https://learn.microsoft.com/api/mcp)
+compatibility: Works best with Microsoft Learn MCP Server (https://learn.microsoft.com/api/mcp). Can also use the mslearn CLI as a fallback.
 ---
 
 # Microsoft Docs
@@ -55,3 +55,23 @@ Fetch after search when:
 - **Accuracy** — live docs, not training data that may be outdated
 - **Completeness** — tutorials have all steps, not fragments
 - **Authority** — official Microsoft documentation
+
+## CLI Alternative
+
+If the Learn MCP server is not available, use the `mslearn` CLI from the command line instead:
+
+```sh
+# Run directly (no install needed)
+npx @microsoft/learn-cli search "azure functions timeout"
+
+# Or install globally, then run
+npm install -g @microsoft/learn-cli
+mslearn search "azure functions timeout"
+```
+
+| MCP Tool | CLI Command |
+|----------|-------------|
+| `microsoft_docs_search(query: "...")` | `mslearn search "..."` |
+| `microsoft_docs_fetch(url: "...")` | `mslearn fetch "..."` |
+
+The `fetch` command also supports `--section <heading>` to extract a single section and `--max-chars <number>` to truncate output.