MCP Directory

How to add FileScopeMCP to Windsurf

Ranks every file by importance, maps dependencies, and keeps AI summaries fresh in the background. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 293★ · stdio · no auth

Windsurf config for FileScopeMCP

git clone https://github.com/admica/FileScopeMCP.git && cd FileScopeMCP && ./build.sh
{
  "mcpServers": {
    "filescopemcp": {
      "command": "node",
      "args": [
        "/path/to/FileScopeMCP/dist/mcp-server.js"
      ]
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the FileScopeMCP config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5FileScopeMCP's tools become available to Cascade.

Before you start

  • Node.js >= 22 and npm
  • Build tools for native modules (better-sqlite3, tree-sitter): build-essential + python3 on Linux, xcode-select on macOS, Visual Studio Build Tools (C++ workload) on Windows
  • Optional: llama.cpp's llama-server (or any OpenAI-compatible HTTP API) for LLM-generated summaries

What FileScopeMCP can do in Windsurf

status

Broker connection, queue depth, LLM progress, watcher state.

find_important_files

Top files by importance score with dependency counts.

get_file_summary

Everything about a file: summary, concepts, change impact, exports, deps, staleness.

list_files

Full file tree (no args) or flat top-N by importance (with maxItems).

find_symbol

Resolve a symbol name to file + line range; supports prefix match via trailing *.

find_callers

Find all symbols that call a named symbol (TS/JS call graph).

find_callees

Find all symbols that a named symbol calls (TS/JS call graph).

search

Search file metadata across symbols, summaries, purpose, and paths.

Security

Proprietary license — Copyright (c) 2026 admica, All rights reserved. Built from source (no npm package); requires native build tools to compile better-sqlite3 and tree-sitter. The optional LLM broker and Nexus dashboard run local HTTP/Unix-socket services; the multi-repo systemd watchers are Linux-only. The `exclude_and_remove` tool is destructive.

FileScopeMCP + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the FileScopeMCP config there under the "mcpServers" key and restart the client.

Is FileScopeMCP safe to use with Windsurf?

Proprietary license — Copyright (c) 2026 admica, All rights reserved. Built from source (no npm package); requires native build tools to compile better-sqlite3 and tree-sitter. The optional LLM broker and Nexus dashboard run local HTTP/Unix-socket services; the multi-repo systemd watchers are Linux-only. The `exclude_and_remove` tool is destructive.

Do I need a local LLM to use it?

No. LLM summaries are optional and require llama.cpp's llama-server (or any OpenAI-compatible HTTP API). Without it, file tracking, dependency mapping, symbol extraction, and call graphs all still work — you just don't get LLM-generated summaries.

Which languages and analysis levels are supported?

TypeScript, JavaScript, Python, C, C++, Rust, Go, Ruby, Lua, Zig, PHP, C#, and Java. AST-level extraction (tree-sitter) is used for TS/JS, Python, C, C++, and Rust; regex-based detection for the rest. Symbol intelligence uses tree-sitter for TS/JS, Python, Go, and Ruby; the call graph (find_callers/find_callees) is TS/JS only.

Which clients does it work with?

Claude Code (auto-registered via ./build.sh using claude mcp add --scope user), plus Hermes Agent, Codex, OpenClaw, Cursor AI, or as a standalone daemon. Agent runtimes discover it via the repo's AGENTS.md.

View repo Full FileScopeMCP page