This repo contains an MCP server (tool provider) and a sample Gemini-based MCP client with an interactive TUI. The server exposes safe, deterministic capabilities; the client handles reasoning and tool orchestration.

Security Model

Path Guard

All filesystem access is restricted to a fixed project root (target-codebase).

Every user-supplied path is validated using a path guard that:

• Resolves paths against the project root
• Rejects absolute paths
• Resolves symlinks using realpath
• Ensures the final resolved path cannot escape the sandbox

This prevents:

• ../ path traversal attacks
• Symlink-based escapes
• Accidental access to system files (e.g. /etc, /home)

Resource Limits

To prevent excessive resource usage and prompt flooding, the server enforces hard limits:

• Maximum file size for reads
• Maximum line count for files
• Maximum directory traversal depth
• Maximum search results

These limits are enforced server-side and cannot be overridden by clients.

Tools

list_files

Lists the structure of a directory within the project.

Purpose

• Provides orientation within the codebase
• Helps decide where to search or inspect next

Input

• dir (optional, project-relative path, defaults to project root)

Output

• Structured directory entries (files and directories)
• Nested up to a fixed maximum depth

Notes

• Common large or irrelevant directories are ignored (e.g. node_modules, .git, build outputs)

search_code

Searches for a plain-text query across the project.

Purpose

• Quickly locate where a concept, identifier, or keyword appears
• Avoid reading unnecessary files

Input

• query (required string)
• dir (optional starting directory, project-relative)

Output

• Project-relative file path
• Line number
• Short line preview

Constraints

• Plain-text search (no regex)
• File size limits enforced
• Total and per-file match limits enforced

read_file

Reads the contents of a single file.

Purpose

• Inspect specific implementation details after locating a file

Input

• path (project-relative file path)

Constraints

• Path must point to a file (directories rejected)
• File size and line limits enforced
• Binary or unreadable files are rejected
• Access to package manager manifests (package.json, package-lock.json) is denied

Typical LLM Workflow

A typical interaction with this MCP server looks like:

1. Call list_files to understand the project structure
2. Call search_code to locate relevant files or identifiers
3. Call read_file to inspect specific code sections

The server intentionally avoids higher-level reasoning and only provides safe primitives that enable the LLM to reason effectively.

Running the Server

Prerequisites

• Node.js 18+
• npm

Install dependencies

npm install

Run the server (dev)

npm run server:dev

Running the Gemini Client

Prerequisites

• Node.js 18+
• Gemini API key (GEMINI_API_KEY env or enter at prompt)

Start the client

npm run client:dev

You will be prompted for:

• Gemini API key (or use GEMINI_API_KEY)
• Gemini model (choices):
  • gemini-2.5-flash-lite (fast, generous free tier)
  • gemini-2.5-flash (balanced, stricter free limits)
  • gemini-2.0-flash-lite (legacy, stable)

Client behavior

• Shows a figlet banner and colored prompts
• Lists available MCP tools
• Chat loop with tool-call handling
• Graceful handling of quota/rate-limit exhaustion (shows a note to retry or change model)

Installation and Usage

The codefinder package provides a command-line interface (CLI) tool for exploring and searching codebases.

Installation

To install codefinder globally, run:

npm install -g @twahaa/codefinder

Alternatively, you can use npx to run it without global installation:

npx @twahaa/codefinder

Usage

Once installed, you can run the codefinder command from your terminal:

codefinder

This will launch an interactive Gemini client that allows you to explore and search codebases using the provided MCP tools. Follow the on-screen prompts to interact with the client.

What the Server Provides (Tools)

The MCP server exposes three safe, deterministic tools:

• list_files: Explore directories within the sandboxed project root (ignores large/irrelevant folders and enforces max depth).
• search_code: Plain-text search with result caps and file size limits.
• read_file: Read a single file with size/line limits; rejects binaries and denies package.json / package-lock.json.

See the sections above for full inputs/outputs and constraints.