@j0hanz/fs-context-mcp 2.0.4 → 2.0.6

package/dist/instructions.md

@@ -1,112 +1,131 @@
-# FS Context MCP Server
+# FS Context MCP Server — AI Usage Instructions
 
-Read-only tools for safe filesystem inspection via the Model Context Protocol (MCP).
-This server can only access explicitly allowed “workspace roots” and never writes to disk.
+Use this server to explore, search, and read filesystem content within allowed workspace roots. All operations are read-only. Prefer using these tools over "remembering" file contents in chat.
 
 ---
 
-## TL;DR (Agent Workflow)
+## Operating Rules
 
-1. `roots` → learn what you can access
-2. `ls` → orient yourself in a directory
-3. `find` → locate candidate files by glob
-4. `grep` → find references/content (text search)
-5. `read` / `read_many` → open the exact files you need
-6. `stat` / `stat_many` → confirm type/size/mime before reading
+- Call `roots` first to confirm accessible directories.
+- Operate by paths relative to roots rather than guessing locations.
+- Batch operations: `read_many` for 2+ files, `stat_many` for 2+ checks.
+- If request is vague, ask clarifying questions before calling tools.
 
----
-
-## Key Rules (Avoid Surprises)
+### Strategies
 
-- **Access is root-scoped:** if `roots` returns an empty list, other tools will fail until the client/CLI config provides roots.
-- **Paths must stay within roots:** attempts to escape (e.g., via `..` or symlinks that resolve outside roots) are denied.
-- **`find` is glob search; `grep` is content search:** use `find` to locate files, `grep` to locate text inside files.
-- **Symlink policy:** directory scans do not traverse symlinked directories; direct symlink targets are allowed only if they resolve within roots.
+- **Discovery:** Unsure directories? Call `roots`. File name pattern? `find`. Content text? `grep`.
+- **Reading:** Multiple files? `read_many`. Large file? `read` with `head`. Binary check? `stat`.
 
 ---
 
-## Quick Reference
+## Data Model
 
-| Goal             | Tool        | Notes                                                                          |
-| ---------------- | ----------- | ------------------------------------------------------------------------------ |
-| Check access     | `roots`     | Always call first                                                              |
-| List a directory | `ls`        | Non-recursive; `includeHidden` optional                                        |
-| Find files       | `find`      | Glob patterns; default excludes common build/deps unless `includeIgnored=true` |
-| Search text      | `grep`      | Literal, case-insensitive text search; can scan a dir or a single file         |
-| Read one file    | `read`      | UTF-8 text; rejects binary; use `head` to preview                              |
-| Read many files  | `read_many` | Up to 100 paths; may skip files if combined reads exceed budget                |
-| File metadata    | `stat`      | Type, size, modified, permissions, mimeType (extension-based)                  |
-| Metadata batch   | `stat_many` | Prefer for 2+ paths                                                            |
+- **Workspace Roots:** Absolute paths; all operations validated against these.
+- **Entries:** `name`, `path` (abs/rel), `type` (file/directory/symlink), `size`, `modified`.
+- **Search Matches:** `file` (relative), `line`, `content` (truncated).
 
 ---
 
-## Practical Recipes
+## Workflows
 
-### Project discovery
+### 1) Project Discovery
 
 ```text
-roots
-ls(path=".")
-read_many(paths=["package.json", "README.md"], head=200)
+roots                                          → confirm access
+ls(path=".")                                   → see top-level structure
+read_many(paths=["package.json", "README.md"]) → understand project
 ```
 
-### Locate & open implementation
+### 2) Find & Read Code
 
 ```text
-find(pattern="src/**/*.ts", maxResults=2000)
-grep(path="src", pattern="registerTool")
-read(path="src/tools.ts", head=200)
+find(pattern="**/*.ts", maxResults=500)        → locate candidates
+grep(path="src", pattern="registerTool")       → find references
+read(path="src/tools.ts", head=100)            → read implementation
 ```
 
-### Check before reading (avoid binary/huge files)
+### 3) Check Before Reading
 
 ```text
-stat(path="docs/logo.png")
-stat_many(paths=["README.md", "dist/index.js"])
+stat(path="docs/logo.png")                     → confirm type/size
+stat_many(paths=["README.md", "dist/index.js"])→ batch metadata check
 ```
 
 ---
 
-## Tool Notes (Behavior That Matters)
+## Tools
+
+### roots
+
+List accessible workspace roots.
+
+- **Use when:** First call, or access errors.
+
+### ls
+
+List immediate directory contents (non-recursive).
+
+- **Args:** `path` (opt), `includeHidden` (opt/false).
+- **Returns:** Name, type, size, modified.
+
+### find
+
+Find files by glob pattern.
+
+- **Args:** `pattern` (req, max 1000ch), `path` (opt), `maxResults` (opt/100), `includeIgnored` (opt/false).
+- **Ref:** `**/*.ts` (recursive), `src/*` (flat). Matches relative paths.
 
-### `find` (glob)
+### grep
 
-- Uses glob patterns like `**/*.ts` or `src/**/index.*`.
-- Default behavior excludes common directories like `node_modules`, `dist`, `.git`, etc.
-  Use `includeIgnored=true` when you explicitly want to search those.
-- Prefer scoping with `path` and limiting with `maxResults` for large repos.
+Search text within file contents (literal, case-insensitive).
 
-Common patterns:
+- **Args:** `pattern` (req), `path` (opt), `includeHidden` (opt/false).
+- **Ref:** Skips binary files and >1MB files.
 
-- `**/*.ts`
-- `src/**/*.{ts,tsx}`
-- `**/*.test.ts`
+### read
+
+Read single text file content.
+
+- **Args:** `path` (req), `head` (opt/lines).
+- **Ref:** Rejects binary. Use `head` for large files.
+
+### read_many
+
+Read multiple text files.
+
+- **Args:** `paths` (req, max 100), `head` (opt).
+- **Ref:** No binary detection (use `stat` first). Returns per-file result/error.
+
+### stat / stat_many
+
+Get metadata for single or multiple paths.
+
+- **Args:** `path` (req) / `paths` (req).
+- **Returns:** Type, size, modified, permissions, mimeType.
+
+---
 
-### `grep` (text search)
+## Response Shape
 
-- Searches for **literal text** (not a user-supplied regex).
-- Matching is **case-insensitive**.
-- By design, it **skips binary files** and **skips very large files** (size limits are configurable by the server environment).
-  “No matches” is not proof that a string doesn’t exist in a binary/large file.
+Success: `{ "ok": true, ...data }`
+Error: `{ "ok": false, "error": { "code": "E_...", "message": "...", "suggestion": "..." } }`
 
-### `read` vs `read_many`
+### Common Errors
 
-- `read` is safest for text: it enforces size limits and refuses binary.
-- `read_many` is best for efficiency (2+ files), but it does **not** do binary detection.
-  If you’re unsure, do `stat_many` first and only read obvious text files.
+- `E_ACCESS_DENIED`: Path outside roots.
+- `E_NOT_FOUND`: Path missing.
+- `E_TOO_LARGE`: File exceeds limit (use `head`).
+- `E_TIMEOUT`: Reduce scope/results.
 
 ---
 
-## Output & Errors
+## Limits
 
-- Each tool returns structured data with `ok: true|false`.
-- On failure you’ll get `ok: false` with an `error` object containing at least `code` and `message` (often `path` and a `suggestion`).
+- **Max Read:** 10MB (file), 1MB (search).
+- **Max Items:** 100 (read/stat batch), 100 (find default).
+- **Timeout:** 30s.
 
-Common error codes:
+## Security
 
-- `E_ACCESS_DENIED` (outside allowed roots)
-- `E_NOT_FOUND`, `E_NOT_FILE`, `E_NOT_DIRECTORY`
-- `E_TOO_LARGE` (use `head`)
-- `E_INVALID_PATTERN` (glob pattern issues in `find`)
-- `E_TIMEOUT` (narrow scope, reduce results)
-- `E_PERMISSION_DENIED`
+- **Read-only:** No writes/deletes.
+- **Sandboxed:** Symlinks cannot escape roots.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/fs-context-mcp",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "mcpName": "io.github.j0hanz/fs-context",
   "description": "🔍 Read-only MCP server for secure filesystem exploration, searching, and analysis",
   "type": "module",