docs update (wip)

src/mcp_client.py

@@ -1,34 +1,56 @@
 # mcp_client.py
 """
-Note(Gemini):
-MCP-style file context tools for manual_slop.
-Exposes read-only filesystem tools the AI can call to selectively fetch file
-content on demand, instead of having everything inlined into the context block.
+MCP Client - Multi-tool filesystem and network operations with sandboxing.
 
-All access is restricted to paths that are either:
- - Explicitly listed in the project's allowed_paths set, OR
- - Contained within an allowed base_dir (must resolve to a subpath of it)
+This module implements a Model Context Protocol (MCP)-like interface for AI
+agents to interact with the filesystem and network. It provides 26 tools
+with a three-layer security model to prevent unauthorized access.
 
-This is heavily inspired by Claude's own tooling limits. We enforce safety here 
-so the AI doesn't wander outside the project workspace.
+Three-Layer Security Model:
+ 1. Allowlist Construction (configure()):
+    - Builds _allowed_paths from project file_items
+    - Populates _base_dirs from file parents and extra_base_dirs
+    - Sets _primary_base_dir for relative path resolution
+    
+ 2. Path Validation (_is_allowed()):
+    - Blacklist check: history.toml, *_history.toml, config, credentials
+    - Explicit allowlist check: _allowed_paths membership
+    - CWD fallback: allows cwd() subpaths if no base_dirs configured
+    - Base directory containment: must be subpath of _base_dirs
+    
+ 3. Resolution Gate (_resolve_and_check()):
+    - Converts relative paths using _primary_base_dir
+    - Resolves symlinks to prevent traversal attacks
+    - Returns (resolved_path, error_message) tuple
+
+Tool Categories:
+ - File I/O: read_file, list_directory, search_files, get_tree
+ - Surgical Edits: set_file_slice, edit_file
+ - AST-Based (Python): py_get_skeleton, py_get_code_outline, py_get_definition,
+   py_update_definition, py_get_signature, py_set_signature, py_get_class_summary,
+   py_get_var_declaration, py_set_var_declaration
+ - Analysis: get_file_summary, get_git_diff, py_find_usages, py_get_imports,
+   py_check_syntax, py_get_hierarchy, py_get_docstring
+ - Network: web_search, fetch_url
+ - Runtime: get_ui_performance
+
+Mutating Tools:
+ The MUTATING_TOOLS frozenset defines tools that modify files. ai_client.py
+ checks this set and routes to pre_tool_callback (GUI approval) if present.
+
+Thread Safety:
+ This module uses module-level global state (_allowed_paths, _base_dirs).
+ Call configure() before dispatch() in multi-threaded environments.
+
+See Also:
+ - docs/guide_tools.md for complete tool inventory and security model
+ - src/ai_client.py for tool dispatch integration
+ - src/shell_runner.py for PowerShell execution
 """
 # mcp_client.py
 
 #MCP-style file context tools for manual_slop.
 
-# Exposes read-only filesystem tools the AI can call to selectively fetch file
-# content on demand, instead of having everything inlined into the context block.
-# All access is restricted to paths that are either:
-#  - Explicitly listed in the project's allowed_paths set, OR
-#  - Contained within an allowed base_dir (must resolve to a subpath of it)
-
-# Tools exposed:
-#   read_file(path)              - return full UTF-8 content of a file
-#   list_directory(path)         - list entries in a directory (names + type)
-#   search_files(path, pattern)  - glob pattern search within an allowed dir
-#   get_file_summary(path)       - return the summarize.py heuristic summary
-#
-
 from __future__ import annotations
 import asyncio
 from pathlib import Path