@mastra/mcp-docs-server 1.2.25 → 1.2.26-alpha.11

package/.docs/reference/workspace/filesystem.md

@@ -269,6 +269,78 @@ const instructions = filesystem.getInstructions?.()
 
 **Returns:** `string`
 
+### `walk(path, options?)`
+
+Native recursive tree walk executed by the provider in as few calls as possible. When implemented, the workspace `list_files` tool uses it instead of issuing one `readdir` round trip per directory, which matters for remote providers (sandboxes, object stores). If `walk` throws, tools fall back to the `readdir`-based walk automatically and log a warning through the workspace logger, since the fallback issues one round trip per directory.
+
+```typescript
+const entries = await filesystem.walk?.('.', { maxDepth: 3 })
+// [{ name: 'index.ts', type: 'file', path: 'src/index.ts' }, ...]
+```
+
+**Parameters:**
+
+**path** (`string`): Directory to walk.
+
+**options.maxDepth** (`number`): Maximum directory depth to descend (root entries are depth 1).
+
+**options.includeHidden** (`boolean`): Include entries whose names start with ".". Defaults to false.
+
+**Returns:** `Promise<WalkEntry[]>`
+
+```typescript
+interface WalkEntry extends FileEntry {
+  path: string // Relative to the walk root, POSIX separators, no leading "./"
+}
+```
+
+### `grep(options)`
+
+Native content search executed by the provider (for example with `rg` or `grep` inside a sandbox). When implemented, the workspace `grep` tool delegates to it instead of downloading every file to search host-side. Throw `UnsupportedGrepPatternError` when a pattern can't run natively so that callers catch it and fall back to the host-side implementation. That fallback is logged at `info` level; any other error from `grep` also triggers the fallback but is logged as a warning, since the host-side search reads every candidate file.
+
+```typescript
+const results = await filesystem.grep?.({
+  pattern: 'TODO',
+  path: '.',
+  caseSensitive: true,
+  includeHidden: false,
+})
+// [{ path: 'src/index.ts', matches: [{ line: 3, column: 6, text: '// TODO: fix' }] }]
+```
+
+**Parameters:**
+
+**options.pattern** (`string`): JavaScript regex source to search for.
+
+**options.path** (`string`): File or directory root to search within.
+
+**options.caseSensitive** (`boolean`): Whether matching is case-sensitive.
+
+**options.includeHidden** (`boolean`): Include hidden files and directories in the search.
+
+**options.maxCountPerFile** (`number`): Maximum matches per file (like grep -m).
+
+**options.maxTotalMatches** (`number`): Global cap on total matches across all files.
+
+**options.contextLines** (`number`): Lines of context to include before and after each match.
+
+**Returns:** `Promise<FilesystemGrepResult[]>`
+
+```typescript
+interface FilesystemGrepResult {
+  path: string // Relative to the search root, POSIX separators
+  matches: FilesystemGrepMatch[]
+}
+
+interface FilesystemGrepMatch {
+  line: number // 1-based line number
+  column: number // 0-based UTF-16 (JS string) index, not a byte offset
+  text: string // Full matched line, without trailing newline
+  before?: string[] // Context lines before the match
+  after?: string[] // Context lines after the match
+}
+```
+
 ## Related
 
 - [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.25",
+  "version": "1.2.26-alpha.11",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,8 +27,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/mcp": "^1.17.3",
-    "@mastra/core": "1.66.0"
+    "@mastra/mcp": "^1.18.0-alpha.1",
+    "@mastra/core": "1.67.0-alpha.4"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -44,9 +44,9 @@
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "vitest": "4.1.10",
-    "@internal/types-builder": "0.0.107",
     "@internal/lint": "0.0.132",
-    "@mastra/core": "1.66.0"
+    "@internal/types-builder": "0.0.107",
+    "@mastra/core": "1.67.0-alpha.4"
   },
   "homepage": "https://mastra.ai",
   "repository": {