Faststack MCP

faststack mcp

Claude Code的本地优先只读MCP服务器。索引和搜索全栈项目 （快速API+反应+PostgreSQL） SQLite支持的FTS, 交叉参考图，以及 文件监视器 自动重新加载——这样克劳德只读取它需要的内容，而不是整个文件。

______________________________________________________________________

快速开始

步骤1--安装

# From local source (development)
cd C:\path\to\faststack-mcp
pip install -e .

# From GitHub
pip install "git+https://github.com/Evaan-devlops/faststack-mcp.git"

# With optional extras
pip install -e ".[watch]"     # file watcher (watchfiles)
pip install -e ".[postgres]"  # PostgreSQL backend (psycopg2-binary)
pip install -e ".[all]"       # both

全球已经有了watchiles/psycopg2？ 无需额外安装——它们 自动拾取。

步骤2——添加到Claude代码

{
  "mcpServers": {
    "faststack": {
      "command": ".venv\\Scripts\\python.exe",
      "args": ["-m", "faststack_mcp"]
    }
  }
}

第3步——为项目建立索引

index_folder("/path/to/your/project")          → project_id + counts
index_folder("/path/to/project", watch=True)   → + auto-reindex on file changes

第四步——探索

get_project_outline(project_id)                → structure at a glance (~17 tokens)
search_symbols(project_id, "createUser")       → find functions, routes, hooks, models
get_symbol(project_id, symbol_id)              → exact code snippet only
find_references(project_id, "get_db")          → all files that import / call a symbol
get_file_context(project_id, "db.py", 120)     → 80 lines around line 120
get_file_outline(project_id, "main.py")        → all symbols in one file
search_text(project_id, "HTTPException")       → fallback full-text search
get_file_tree(project_id)                      → directory tree
list_projects()                                → all indexed projects
invalidate_cache(project_id)                   → force full re-index
get_token_usage()                              → cost + per-session averages

______________________________________________________________________

工具参考（12个工具）

find_references --依赖性影响分析

find_references(project_id, "get_db")
→ {
    symbol_name: "get_db",
    files_found: 3,
    total_usages: 3,
    references: [
      { file_path: "users.py",  usages: [{ line: 5,  context: "from db import get_db" }] },
      { file_path: "auth.py",   usages: [{ line: 12, context: "db = get_db()" }] },
      { file_path: "orders.py", usages: [{ line: 8,  context: "from db import get_db" }] }
    ]
  }

在修改共享符号之前使用，以了解爆炸半径。使用构建的导入图 在...期间 index_folder （快速路径），将整词正则表达式扫描作为回退。

get_file_context --周围代码窗口

get_file_context(project_id, "src/db.py", around_line=120, radius=40)
→ lines 80–160, line 120 marked with >>>

使用时 get_symbol 太窄了——例如，理解符号边界周围的代码， 检查迁移函数或读取错误处理上下文。

______________________________________________________________________

存储后端

被控制 FASTSTACK_STORAGE 环境变量。

SQLite（默认）

无需配置。特征：

• FTS5虚拟表上的符号名称+合格名称+签名
• FTS5+LIKE组合回退（手柄 get_db, create_user 下划线名称）
• refs 桌子用于 find_references 查找
• WAL模式——索引时并发读取

PostgreSQL

export FASTSTACK_STORAGE=postgres
export DATABASE_URL=postgresql://user:pass@localhost:5433/mydb

特征：

• GENERATED ALWAYS AS tsvector列+GIN索引（零维护FTS）
• ts_rank 相关性排序+ILIKE补充
• 表前缀 faststack_* （与您的应用程序表没有冲突）
• 通过批量插入 execute_values （500行/页）
• faststack_references 桌子用于 find_references

psycopg2-binary 必须安装(pip install psycopg2-binary 或 pip install faststack-mcp[postgres]).

______________________________________________________________________

文件监视器（自动重新索引）

# Start watcher alongside indexing
index_folder("/path/to/project", watch=True)

• 用途 watchfiles （安装： pip install watchfiles 或 pip install faststack-mcp[watch])
• 1.5秒去抖动——在重新索引火灾之前，快速保存是分批进行的
• 后台守护进程线程--未阻止Claude
• 如果 watchfiles 未安装

______________________________________________________________________

交叉参考图

期间自动构建 index_folder.跟踪每一个 import 和 from X import Y 跨Python和TypeScript/JavaScript文件的语句。

图形存储在索引中，并通过以下方式查询 find_references。它能够：

• 在一次工具调用中，“什么调用/导入此符号？”
• 重构共享实用程序之前的影响分析
• 理解FastAPI依赖注入(Depends(get_db))

______________________________________________________________________

搜索-- include_synthetic 行为

根据具体情况显示或隐藏合成符号（自动生成的模型字段、配置键） 根据上下文：

明确覆盖： search_symbols(project_id, "User", include_synthetic=True)

______________________________________________________________________

令牌使用分析

get_token_usage(last_n=20)
→ {
    totals: { input_tokens, output_tokens, estimated_cost_usd },
    averages: { input_tokens_per_session, cost_usd_per_session },
    tool_breakdown: { get_symbol: { calls: 18, est_saved: 136800 }, ... },
    estimated_tokens_saved_by_mcp: 209000
  }

需要插入止动钩 ~/.claude/settings.json 以记录会话数据。

______________________________________________________________________

支持的文件类型

来源： .py .ts .tsx .js .jsx .sql

配置/元： .json .jsonl .toml .yaml .yml .ini

命名文件： package.json pyproject.toml tsconfig.json tsconfig.app.json tsconfig.node.json vite.config.* alembic.ini eslint.config.js tailwind.config.js tailwind.config.ts manifest.json chunks.jsonl index.faiss bunfig.toml .env.example

跳过dirs： .git node_modules .next dist build coverage .venv venv __pycache__ .mypy_cache .pytest_cache .idea .vscode .claude

跳过敏感文件： .env .env.* *.pem *.key *.p12 id_rsa id_ed25519 (.env* 文件选择通过 include_env_files=True)

______________________________________________________________________

解析器

______________________________________________________________________

安全

• 所有文件读取路径仅限于索引项目根目录
• 每次查找时都会进行Symlink转义检查
• 二进制文件检测（空字节扫描）
• 文件大小上限（默认2 MB）
• 默认情况下跳过敏感文件模式
• 不对项目文件执行写入或shell操作
• SQLite缓存隔离在 ~/.faststack-mcp/

______________________________________________________________________

安装选项

# Local dev
pip install -e "C:\path\to\faststack-mcp"

# GitHub
pip install "git+https://github.com/Evaan-devlops/faststack-mcp.git"

# With extras
pip install -e ".[watch]"       # watchfiles — file watcher
pip install -e ".[postgres]"    # psycopg2-binary — PostgreSQL backend
pip install -e ".[all]"         # both

环境变量

发展

python -m venv .venv
.venv\Scripts\python -m pip install -e .
python -m py_compile src/faststack_mcp/server.py  # syntax check
pytest tests/

Env解析

• .env.example 默认情况下使用掩码值进行索引(***MASKED***)
• .env 和 .env.* 跳过，除非 include_env_files=True
• 原始值从未持续存在