folderinfo-mcp

Ultra-simple MCP server for folder exploration.

Tools

• tree: formatted directory tree
• ls: list items in directory
• recursive-ls: recursive listing
• folder-info: markdown report (tree, cwd, file contents)

Parameters (all tools)

| Name | Type | Description | | --------------- | -------- | ----------------------------------------- | | dir | string | Target directory (default cwd) | | filetype | string[] | Extensions (without dot) to include | | excludedFolders | string[] | Regex or glob patterns to exclude folders | | excludedFiles | string[] | Regex or glob patterns to exclude files |

Usage (Claude Desktop)

Add to config:

{
  "mcpServers": {
    "folderinfo": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/folderinfo-mcp/dist/index.js"]
    }
  }
}

Dev:

pnpm install
pnpm run dev

Build & Run:

pnpm run build
pnpm start

Test Tools:

pnpm test

## Global CLI Install / Wrapper

The published binary uses a small ESM wrapper (`bin/folderinfo-mcp.mjs`) with a shebang. This avoids losing the shebang when rebuilding `dist/`.

Install globally (development link):

```bash
pnpm build
pnpm link --global
folderinfo-mcp  # should print: folderinfo-mcp server running

Or via npm after publish:

npm install -g folderinfo-mcp
folderinfo-mcp

If you prefer to reference directly in a Claude config without global install:

{
  "mcpServers": {
    "folderinfo": {
      "command": "node",
      "args": ["/absolute/path/folderinfo-mcp/dist/index.js"]
    }
  }
}

Why a Wrapper?

Because TypeScript outputs ESM files without a shebang, executing dist/index.js directly as a binary (from the package bin field) would fail or silently do nothing on some shells. The wrapper adds:

1. Shebang line (#!/usr/bin/env node)
2. Stable path resolution to dist/index.js
3. Clear error message if startup fails

Troubleshooting

| Issue | Cause | Fix | | ------------------------------------- | ---------------------- | --------------------------------------- | | Running folderinfo-mcp does nothing | Old global link cached | Re-run pnpm link --global after build | | Permission denied | Missing execute bit | chmod +x bin/folderinfo-mcp.mjs | | Not updated after edits | Forgot to rebuild | pnpm build then re-link |