# Codebase Structure

**Analysis Date:** 2026-01-26

## Directory Layout

```
/Users/luutuankiet/dev/fs-mcp/
├── src/fs_mcp/                    # Main package source code
│   ├── __init__.py                # Package initialization (empty)
│   ├── __main__.py                # CLI entry point and orchestration
│   ├── server.py                  # MCP server core, tool definitions, security
│   ├── edit_tool.py               # Edit proposal/review logic and utilities
│   ├── http_runner.py             # HTTP transport subprocess entry point
│   └── web_ui.py                  # Streamlit web UI for tool testing
├── tests/                         # Test suite
│   ├── test_server.py             # Tests for server tools and security
│   └── test_edit_tool.py          # Tests for edit tool functionality
├── pyproject.toml                 # Python project metadata and dependencies
├── README.md                      # Project documentation
├── CHANGELOG.md                   # Version history
├── gsd-lite/                      # GSD task tracking (not runtime code)
│   ├── STATE.md
│   ├── WORK.md
│   ├── HISTORY.md
│   ├── INBOX.md
│   └── template/                  # Template files for GSD
├── .planning/                     # Planning and documentation
│   └── codebase/                  # Codebase analysis documents (this location)
├── .project/                      # Project metadata
├── tmp/                           # Temporary runtime files (not committed)
│   ├── attachments/
│   └── partial_repo/
└── .venv/                         # Virtual environment (not committed)
```

## Directory Purposes

**`src/fs_mcp/`:**
- Purpose: Main package implementation
- Contains: Python modules for CLI, MCP server, transports, UI
- Key files: All 6 `.py` files are essential to runtime

**`tests/`:**
- Purpose: Unit and integration tests
- Contains: Pytest test files
- Key files: `test_server.py` (security, tools), `test_edit_tool.py` (edit logic)

**`gsd-lite/`:**
- Purpose: GSD (GitHub Seed Deployment) task and issue tracking
- Contains: Markdown state files and template directory
- Key files: Not loaded at runtime; for development planning only

**`.planning/codebase/`:**
- Purpose: Codebase analysis and documentation
- Contains: Architecture, structure, conventions, testing docs
- Key files: Generated by `/gsd:map-codebase` command

**`tmp/`:**
- Purpose: Development scratch space
- Contains: Downloaded/experimental code (not part of runtime)
- Note: Not committed to repository

## Key File Locations

**Entry Points:**
- `src/fs_mcp/__main__.py`: Command-line entry point (invoked by `fs-mcp` command or `python -m fs_mcp`)
- `src/fs_mcp/http_runner.py`: HTTP server subprocess entry point
- `src/fs_mcp/web_ui.py`: Streamlit UI entry point (invoked by `streamlit run`)

**Configuration:**
- `pyproject.toml`: Package metadata, dependencies, build configuration
- `src/fs_mcp/__main__.py` lines 30-48: CLI argument parser with UI/HTTP options

**Core Logic:**
- `src/fs_mcp/server.py`: MCP server initialization, tool definitions, path validation (lines 37-124)
- `src/fs_mcp/edit_tool.py`: File editing with proposal/review workflow (lines 66-338)

**Testing:**
- `tests/test_server.py`: Tool functionality and security tests
- `tests/test_edit_tool.py`: Edit tool behavior tests

**Documentation:**
- `README.md`: Project overview, features, quick start
- `CHANGELOG.md`: Version history
- `.planning/codebase/`: This analysis and related docs

## Naming Conventions

**Files:**
- Descriptive lowercase with underscores: `__main__.py`, `edit_tool.py`, `http_runner.py`, `web_ui.py`
- Test files follow pytest convention: `test_*.py`
- Package entry: `__init__.py`

**Directories:**
- Lowercase with underscores: `fs_mcp`, `.planning`, `gsd-lite`, `.project`
- Standard Python layout: `src/` for source, `tests/` for tests, `.venv/` for virtual environment

**Functions:**
- Lowercase with underscores: `initialize()`, `validate_path()`, `read_files()`, `propose_and_review_logic()`
- Tool decorators: `@mcp.tool()` marks public MCP tools

**Classes:**
- PascalCase: `EditResult`, `FileReadRequest`, `RooStyleEditTool`

**Constants:**
- Uppercase with underscores: `ALLOWED_DIRS`, `USER_ACCESSIBLE_DIRS`, `IS_VSCODE_CLI_AVAILABLE`, `APPROVAL_KEYWORD`, `TARGET_TOKENS_PER_CHUNK`

## Where to Add New Code

**New Filesystem Tool (e.g., delete_file, rename_batch):**
- Primary code: `src/fs_mcp/server.py`
- Pattern: Add new function with `@mcp.tool()` decorator, validate path via `validate_path()`, return string or dict result
- Security: Always call `validate_path()` before any path operation
- Example location: After existing tools like `append_text()` (line 601+)
- Tests: Add test case in `tests/test_server.py` following existing patterns

**New Interactive Review Feature (e.g., diff approval modes):**
- Primary code: `src/fs_mcp/edit_tool.py`
- Pattern: Extend `propose_and_review_logic()` function, add new response types or session workflows
- Temporary files: Store in `tempfile.gettempdir()` with `mcp_review_` prefix for path validation compatibility
- Tests: Add test case in `tests/test_edit_tool.py`

**New HTTP Configuration (e.g., authentication, custom headers):**
- Primary code: `src/fs_mcp/http_runner.py`
- Pattern: Add middleware or modify `server.mcp.run()` call
- CLI flags: Add new arguments to `__main__.py` parser, pass to subprocess

**New UI Feature (e.g., file diff viewer, batch operations):**
- Primary code: `src/fs_mcp/web_ui.py`
- Pattern: Add new Streamlit components, tabs, or forms
- Tool execution: Use `execute_tool()` function (line 205) to call server tools
- Schema handling: Use `convert_to_gemini_schema()` for Gemini compatibility

**New CLI Mode or Orchestration:**
- Primary code: `src/fs_mcp/__main__.py`
- Pattern: Add new argument group, conditional process spawning, signal handling
- Example: `if args.run_stdio: ...` to add Stdio mode alongside existing HTTP/UI

**Utilities and Helpers:**
- Location: Appropriate module based on concern
  - File analysis: `src/fs_mcp/server.py` (e.g., `_calculate_adaptive_chunk_size()`)
  - Editing validation: `src/fs_mcp/edit_tool.py` (e.g., `normalize_line_endings()`)
  - Schema transformation: `src/fs_mcp/web_ui.py` (e.g., `prune_for_gemini_strictness()`)

## Special Directories

**`tmp/` Directory:**
- Purpose: Development scratch space for test data, downloaded files, experiments
- Generated: Yes (by developers during dev)
- Committed: No (in .gitignore)
- Note: Runtime creates session directories here for propose_and_review workflow

**Session Directories (Runtime):**
- Location: `{tempfile.gettempdir()}/mcp_review_<random>`
- Generated: By `propose_and_review_logic()` for each interactive edit
- Committed: No (temporary)
- Cleanup: Automatic after `commit_review()` or on error
- Security: Path validation restricts access to `current_*` and `future_*` files

**`gsd-lite/` Directory:**
- Purpose: GSD-based task/issue tracking (workflow management)
- Generated: No (manually maintained)
- Committed: Yes (includes planning history)
- Runtime impact: None (loaded only by GSD orchestrator, not by fs-mcp server)

**`.planning/codebase/` Directory:**
- Purpose: Analysis documents generated by `/gsd:map-codebase`
- Generated: Yes (by Claude analysis agent)
- Committed: Yes (includes ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, etc.)
- Runtime impact: None (reference only for future development)

---

*Structure analysis: 2026-01-26*
