@twahaa/codefinder 1.0.0

package/LICENSE

@@ -0,0 +1,16 @@
+ISC License
+
+Copyright (c) 2025, CodeFinder contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+

package/README.md

@@ -0,0 +1,188 @@
+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
+
+```bash
+npm install
+```
+
+### Run the server (dev)
+
+```bash
+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
+
+```bash
+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)
+
+---
+
+## 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.
+
+---

package/build/cli/search.js

@@ -0,0 +1,37 @@
+import { searchCode } from "../tools/searchCode.js";
+function printUsage() {
+    console.log(`
+Usage:
+  search <query> [directory]
+
+Examples:
+  search TODO
+  search "import fs" src
+`);
+}
+const args = process.argv.slice(2);
+if (args.length === 0) {
+    printUsage();
+    process.exit(1);
+}
+const query = args[0];
+const dir = args[1];
+try {
+    const results = searchCode(query, dir);
+    if (results.length === 0) {
+        console.log("No matches found.");
+        process.exit(0);
+    }
+    for (const r of results) {
+        console.log(`${r.filePath}:${r.lineNumber}  ${r.preview}`);
+    }
+}
+catch (err) {
+    if (err instanceof Error) {
+        console.error("Error:", err.message);
+    }
+    else {
+        console.error("Unknown error");
+    }
+    process.exit(1);
+}

package/build/client.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { config } from "dotenv";
+config();
+import { intro, outro, text, note, spinner, isCancel, select, } from "@clack/prompts";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { SchemaType, GoogleGenerativeAI, } from "@google/generative-ai";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { logError, logModelText, logToolCall, logToolResult, renderLogo, } from "./ui/openTUI.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const builtServerPath = path.resolve(__dirname, "server.js");
+renderLogo();
+intro("CodeFinder by TWAHaa");
+note("MCP + Gemini Client");
+if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error("This CLI requires a TTY. Please run in an interactive terminal.");
+    process.exit(1);
+}
+const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: [builtServerPath],
+});
+const mcpClient = new Client({
+    name: "CodeFinder",
+    version: "1.0.0",
+});
+await mcpClient.connect(transport);
+const apiKeyInput = await text({
+    message: "Enter Gemini API key (leave blank to use GEMINI_API_KEY env):",
+    placeholder: "AIza...",
+});
+if (isCancel(apiKeyInput)) {
+    outro("Cancelled.");
+    process.exit(0);
+}
+const geminiApiKey = (typeof apiKeyInput === "string" ? apiKeyInput.trim() : "") ||
+    process.env.GEMINI_API_KEY;
+if (!geminiApiKey) {
+    console.error("A Gemini API key is required. Set env or enter it at prompt.");
+    process.exit(1);
+}
+const tools = await mcpClient.listTools();
+note(tools.tools.length
+    ? `Tools: ${tools.tools.map((t) => t.name).join(", ")}`
+    : "No tools available.");
+const geminiTools = tools.tools.map((tool) => {
+    const inputSchema = tool.inputSchema;
+    const properties = inputSchema &&
+        typeof inputSchema === "object" &&
+        "properties" in inputSchema
+        ? (inputSchema.properties ??
+            {})
+        : {};
+    const required = inputSchema && typeof inputSchema === "object" && "required" in inputSchema
+        ? inputSchema.required
+        : undefined;
+    return {
+        name: tool.name,
+        description: tool.description ?? "",
+        parameters: {
+            type: SchemaType.OBJECT,
+            properties,
+            required,
+        },
+    };
+});
+const modelChoice = await select({
+    message: "Choose a Gemini model",
+    options: [
+        {
+            value: "gemini-2.5-flash-lite",
+            label: "Gemini 2.5 Flash-Lite (fast, generous free tier)",
+        },
+        {
+            value: "gemini-2.5-flash",
+            label: "Gemini 2.5 Flash (balanced, stricter free limits)",
+        },
+        {
+            value: "gemini-2.0-flash-lite",
+            label: "Gemini 2.0 Flash / Flash-Lite (legacy, stable)",
+        },
+    ],
+    initialValue: "gemini-2.5-flash-lite",
+});
+if (isCancel(modelChoice)) {
+    outro("Cancelled.");
+    process.exit(0);
+}
+const modelName = typeof modelChoice === "string" ? modelChoice : "gemini-2.5-flash-lite";
+note(`Using model: ${modelName}`);
+const genAI = new GoogleGenerativeAI(geminiApiKey);
+const model = genAI.getGenerativeModel({
+    model: modelName,
+    tools: [
+        {
+            functionDeclarations: geminiTools,
+        },
+    ],
+});
+const chat = model.startChat({ history: [] });
+function isResourceExhausted(err) {
+    const anyErr = err;
+    const msg = anyErr?.message?.toLowerCase?.() ?? "";
+    const statusText = anyErr?.statusText?.toLowerCase?.() ?? "";
+    return (anyErr?.status === 429 ||
+        statusText.includes("too many") ||
+        msg.includes("resource has been exhausted") ||
+        msg.includes("quota") ||
+        msg.includes("rate limit"));
+}
+async function handleTurn(userText) {
+    let result;
+    try {
+        result = await chat.sendMessage(userText);
+    }
+    catch (err) {
+        if (isResourceExhausted(err)) {
+            note("Resource/quota exhausted for this model. Try again later or pick another model.");
+            return;
+        }
+        throw err;
+    }
+    let response = result.response;
+    // Continue handling tool calls until the model stops requesting them
+    while (true) {
+        const call = response.functionCalls()?.[0];
+        if (!call) {
+            logModelText(response.text());
+            return;
+        }
+        const { name, args } = call;
+        const parsedArgs = args && typeof args === "object"
+            ? args
+            : {};
+        logToolCall(name, parsedArgs);
+        const toolResult = await mcpClient.callTool({
+            name,
+            arguments: parsedArgs,
+        });
+        logToolResult(toolResult.content);
+        let followUp;
+        try {
+            followUp = await chat.sendMessage([
+                {
+                    functionResponse: {
+                        name,
+                        response: { content: toolResult.content },
+                    },
+                },
+            ]);
+        }
+        catch (err) {
+            if (isResourceExhausted(err)) {
+                note("Resource/quota exhausted while sending tool result. Try again later or pick another model.");
+                return;
+            }
+            throw err;
+        }
+        response = followUp.response;
+    }
+}
+console.log("Chat ready. Type your question (or 'exit' to quit).");
+while (true) {
+    const queryInput = await text({
+        message: "You",
+        placeholder: "Ask me anything (type 'exit' to quit)",
+    });
+    if (isCancel(queryInput)) {
+        outro("Goodbye!");
+        break;
+    }
+    const query = typeof queryInput === "string" ? queryInput.trim() : String(queryInput);
+    if (!query)
+        continue;
+    if (query.toLowerCase() === "exit") {
+        outro("Goodbye!");
+        break;
+    }
+    try {
+        const spin = spinner();
+        spin.start("Sending to Gemini...");
+        await handleTurn(query);
+        spin.stop("Done.");
+    }
+    catch (err) {
+        logError(err);
+    }
+}

package/build/server.js

@@ -0,0 +1,122 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import z from "zod";
+import { searchCode } from "./tools/searchCode.js";
+import { readFile } from "./tools/readFile.js";
+import { listFile } from "./tools/listFile.js";
+const server = new McpServer({
+    name: "CodeFinder",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+        resources: {},
+        prompts: {},
+    },
+});
+server.registerTool("search_code", {
+    description: "Search for a text query inside a directory",
+    inputSchema: {
+        query: z.string().min(1).describe("Text to search for"),
+        dir: z.string().optional().describe("Relative directory path"),
+    },
+}, async ({ query, dir }) => {
+    try {
+        const results = searchCode(query, dir);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(results, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: err instanceof Error
+                            ? `Error: ${err.message}`
+                            : "Unknown error",
+                    }),
+                },
+            ],
+        };
+    }
+});
+server.registerTool("list_files", {
+    description: "List the files in a directory",
+    inputSchema: {
+        path: z.string().min(0).optional().describe("Relative path to the directory"),
+    },
+}, async ({ path }) => {
+    try {
+        const files = listFile(path);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(files, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: err instanceof Error
+                            ? `Error: ${err.message}`
+                            : "Unknown error",
+                    }),
+                },
+            ],
+        };
+    }
+});
+server.registerTool("read_file", {
+    description: "Read the contents of a text file safely",
+    inputSchema: {
+        path: z.string().min(1).describe("Relative path to the file"),
+    },
+}, async ({ path }) => {
+    try {
+        const content = readFile(path);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: content,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: err instanceof Error
+                            ? `Error: ${err.message}`
+                            : "Unknown error",
+                    }),
+                },
+            ],
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running");
+}
+main().catch((err) => {
+    console.error("Failed to start MCP server:", err);
+    process.exit(1);
+});

package/build/tools/listFile.js

@@ -0,0 +1,50 @@
+import fs from "fs";
+import path from "path";
+import { resolveSafePath } from "../utils/pathGuard.js";
+const IGNORE = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    ".env",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "package.json",
+]);
+const MAX_DEPTH = 2;
+export function listFile(dir = ".") {
+    const safeDir = resolveSafePath(dir);
+    const stats = fs.statSync(safeDir);
+    if (!stats.isDirectory()) {
+        throw new Error("Path must be a directory");
+    }
+    return walkDirectory(safeDir, 0);
+}
+function walkDirectory(absoluteDir, depth) {
+    const entires = fs.readdirSync(absoluteDir, { withFileTypes: true });
+    const result = [];
+    for (const entry of entires) {
+        if (IGNORE.has(entry.name))
+            continue;
+        const entryPath = path.join(absoluteDir, entry.name);
+        if (entry.isFile()) {
+            result.push({
+                name: entry.name,
+                type: "file",
+            });
+        }
+        if (entry.isDirectory()) {
+            const dirEntry = {
+                name: entry.name,
+                type: "directory",
+            };
+            if (depth < MAX_DEPTH) {
+                dirEntry.children = walkDirectory(entryPath, depth + 1);
+            }
+            result.push(dirEntry);
+        }
+    }
+    return result;
+}

package/build/tools/readFile.js

@@ -0,0 +1,26 @@
+import fs from "fs";
+import { resolveSafePath } from "../utils/pathGuard.js";
+export function readFile(userPath) {
+    const safePath = resolveSafePath(userPath);
+    const stats = fs.statSync(safePath);
+    const MAX_SIZE = 200 * 1024;
+    const MAX_LINES = 1000;
+    if (!stats.isFile()) {
+        throw new Error("The path should specify a file not a directory");
+    }
+    if (stats.size > MAX_SIZE) {
+        throw new Error("File too big");
+    }
+    let content;
+    try {
+        content = fs.readFileSync(safePath, "utf-8");
+    }
+    catch {
+        throw new Error("File not readable as text");
+    }
+    const lines = content.split(/\r?\n/).length;
+    if (lines > MAX_LINES) {
+        throw new Error("Too many lines!");
+    }
+    return content;
+}

package/build/tools/searchCode.js

@@ -0,0 +1,46 @@
+import fs from "fs";
+import path from "path";
+import { resolveSafePath } from "../utils/pathGuard.js";
+import { listFile } from "./listFile.js";
+import { flattenFileTree } from "../utils/flattenFIleTrees.js";
+function isEmpty(str) {
+    return !str || str.trim().length === 0;
+}
+export function searchCode(query, dir) {
+    if (isEmpty(query)) {
+        throw new Error("The query is empty");
+    }
+    const rootDir = resolveSafePath(dir ?? ".");
+    const stats = fs.statSync(rootDir);
+    if (!stats.isDirectory()) {
+        throw new Error("The given path is not a directory");
+    }
+    const tree = listFile(rootDir);
+    const files = flattenFileTree(tree, rootDir);
+    const results = [];
+    const q = query.trim().toLowerCase();
+    for (const filePath of files) {
+        const ext = path.extname(filePath);
+        if ([".png", ".jpg", ".jpeg", ".zip", ".exe", ".pdf"].includes(ext)) {
+            continue;
+        }
+        let content;
+        try {
+            content = fs.readFileSync(filePath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].toLowerCase().includes(q)) {
+                results.push({
+                    filePath,
+                    lineNumber: i + 1,
+                    preview: lines[i].trim(),
+                });
+            }
+        }
+    }
+    return results;
+}

package/build/ui/openTUI.js

@@ -0,0 +1,61 @@
+import figlet from "figlet";
+import chalk from "chalk";
+const divider = chalk.gray("-".repeat(50));
+export function renderLogo() {
+    const text = figlet.textSync("CodeFinder", {
+        font: "Standard",
+        horizontalLayout: "default",
+        verticalLayout: "default",
+    });
+    console.log("\n" + chalk.magenta(text));
+    console.log(chalk.whiteBright("by TWAHaa"));
+    console.log(divider);
+}
+export function renderHeader(title, subtitle) {
+    console.log("\n" + divider);
+    console.log(chalk.bold.white(title));
+    if (subtitle)
+        console.log(chalk.gray(subtitle));
+    console.log(divider);
+}
+export function renderTools(tools) {
+    if (!tools.length) {
+        console.log(chalk.yellow("No tools available."));
+        console.log(divider);
+        return;
+    }
+    console.log(chalk.cyan("Available tools:"));
+    for (const tool of tools) {
+        const desc = tool.description ? ` — ${tool.description}` : "";
+        console.log(`${chalk.green("•")} ${chalk.white(tool.name)}${chalk.gray(desc)}`);
+    }
+    console.log(divider);
+}
+export function logToolCall(name, args) {
+    console.log(divider);
+    console.log(`${chalk.blue("Tool call")} ${chalk.gray("→")} ${chalk.white(name)}`);
+    console.log(formatJSON(args));
+    console.log(divider);
+}
+export function logToolResult(result) {
+    console.log(chalk.blue("Tool result:"));
+    console.log(formatJSON(result));
+    console.log(divider);
+}
+export function logModelText(text) {
+    console.log(chalk.magenta("Gemini:"));
+    console.log(chalk.white(text.trim() || "(no text)"));
+    console.log(divider);
+}
+export function logError(err) {
+    console.error(chalk.red("Error:"), err);
+    console.log(divider);
+}
+function formatJSON(data) {
+    try {
+        return chalk.gray(JSON.stringify(data, null, 2));
+    }
+    catch {
+        return String(data);
+    }
+}

package/build/utils/flattenFIleTrees.js

@@ -0,0 +1,13 @@
+export function flattenFileTree(nodes, rootPath) {
+    let files = [];
+    for (const node of nodes) {
+        const fullPath = `${rootPath}/${node.name}`;
+        if (node.type === "file") {
+            files.push(fullPath);
+        }
+        else if (node.children) {
+            files.push(...flattenFileTree(node.children, fullPath));
+        }
+    }
+    return files;
+}

package/build/utils/pathGuard.js

@@ -0,0 +1,18 @@
+import fs from "fs";
+import path from "path";
+const PROJECT_ROOT = process.cwd();
+export function resolveSafePath(userPath) {
+    userPath = userPath.trim();
+    const candidatePath = path.resolve(PROJECT_ROOT, userPath);
+    let realCandidatePath;
+    try {
+        realCandidatePath = fs.realpathSync(candidatePath);
+    }
+    catch {
+        throw new Error("Path does not exist or cannot be accessed");
+    }
+    if (realCandidatePath !== PROJECT_ROOT && !realCandidatePath.startsWith(PROJECT_ROOT + path.sep)) {
+        throw new Error("Path escapes project root");
+    }
+    return realCandidatePath;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "@google/generative-ai": "^0.24.1",
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "dotenv": "^17.2.3",
+    "chalk": "^5.3.0",
+    "figlet": "^1.9.4",
+    "zod": "^3.25.76"
+  },
+  "name": "@twahaa/codefinder",
+  "version": "1.0.0",
+  "description": "MCP server and interactive Gemini client for exploring and searching codebases.",
+  "main": "build/server.js",
+  "exports": {
+    ".": "./build/server.js",
+    "./client": "./build/client.js"
+  },
+  "type": "module",
+  "devDependencies": {
+    "@modelcontextprotocol/inspector": "^0.18.0",
+    "@types/node": "^25.0.3",
+    "@types/figlet": "^1.5.8",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "clean": "rm -rf build",
+    "build": "tsc",
+    "prepare": "npm run build",
+    "client:dev": "tsx src/client.ts",
+    "search": "tsx src/cli/search.ts",
+    "server:test": "echo \"Error: no test specified\" && exit 1",
+    "server:build": "tsc",
+    "server:build:watch": "tsc --watch",
+    "server:dev": "tsx src/server.ts",
+    "server:inspect": "DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector npm run server:dev"
+  },
+  "bin": {
+    "codefinder": "build/client.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [],
+  "author": "",
+  "license": "ISC"
+}