S
Semfora
Reference

MCP Tools Reference

Complete reference for all 18 MCP tools available in Semfora Engine. Tools marked as "Recommended" are the best starting points for common workflows.

get_contextRecommendedContext

Get quick git and project context in ~200 tokens. Use this FIRST when starting work on a repository to understand: current branch, last commit, index status, and project type.

get_overviewRecommendedContext

Get the repository overview from a pre-built sharded index. Returns a compact summary with framework detection, module list (max 30), risk breakdown, and entry points.

get_languagesContext

Get all programming languages supported by semfora-engine for semantic analysis.

server_statusContext

Get server status including mode, features, and optionally detailed layer status. Requires persistent mode for layer details.

analyzeRecommendedAnalysis

Unified analysis: auto-detects file, directory, or module. For files: extracts semantic info. For directories: returns overview with module grouping. For modules: returns detailed semantic info from index. Supports line ranges for large files.

analyze_diffRecommendedAnalysis

Use for code reviews - analyzes changes between git branches or commits semantically. Shows new/modified symbols, changed dependencies, and risk assessment. Use target_ref='WORKING' for uncommitted changes. Supports pagination.

searchRecommendedSearch

Unified search - runs BOTH symbol and semantic search by default (hybrid mode). Returns symbol matches AND conceptually related code in one call. Use mode='symbols' for exact name, mode='semantic' for BM25, or mode='raw' for regex patterns.

get_symbolSymbols

Get detailed semantic information for symbol(s). Three modes: (1) Single hash: use symbol_hash. (2) Batch: use hashes array (max 20). (3) Location: use file+line to find symbol at that position.

get_sourceRecommendedSymbols

Get source code for symbol(s) or line range. Three modes: (1) Batch: use hashes array (max 20, most efficient). (2) Single hash: use symbol_hash. (3) File+lines: use file_path with start_line/end_line.

get_fileSymbols

Get symbols from a file or module (mutually exclusive). Use file_path for file-centric view, or module for module-centric view. Returns lightweight index entries with optional source snippets. Max 200 results.

get_callersRecommendedCall Graph

Use before modifying existing code to understand impact radius. Answers 'what functions call this symbol?' Shows what will break if you change this function. Returns direct callers with optional depth control (max 3, max 50 results).

get_callgraphCall Graph

Understand code flow and dependencies between functions. Use with filters (module, symbol) for targeted analysis - unfiltered output can be very large (max 2000 edges). Set export='sqlite' to export to SQLite database with batching.

validateRecommendedQuality

Unified quality audit - validates complexity, duplicates, and impact radius. Auto-detects scope: provide symbol_hash OR file_path+line for single symbol, file_path alone for all symbols in file, or module for module-level validation. Max 500 symbols.

find_duplicatesQuality

Unified duplicate detection. Codebase scan (default): Find all duplicate clusters for health audits (max 200 clusters). Single symbol check: Pass symbol_hash to check one symbol before writing new code or during refactoring.

indexRecommendedIndexing

Unified index management - smart refresh by default (checks freshness, rebuilds only if stale within max_age). Use force=true to always regenerate. Returns index status and statistics. Supports incremental indexing.

testTesting

Unified test runner - runs tests by default (auto-detects framework: pytest, cargo, npm, vitest, jest, go). Use detect_only=true to only detect available test frameworks without running. Supports filtering and timeout control.

lintRecommendedLinting

Unified linter - auto-detects and runs linters across 26 linters and 16 languages. Use detect_only=true to list available linters. Use mode='fix' to auto-fix issues. Supports severity filtering and safety controls.

prep_commitRecommendedCommit

Prepare information for writing a commit message. Gathers git context, analyzes staged and unstaged changes semantically, and returns a compact summary with optional complexity metrics. This tool NEVER commits - it only provides information.

Recommended Workflows

Starting with a New Codebase

Use these tools in order to understand a new repository:

  1. get_context — Quick orientation (~200 tokens)
  2. get_overview — Architecture and modules (max 30)
  3. search — Find specific functionality (hybrid mode)
  4. get_source — Read the code with context

Code Review

Analyze changes before merging:

  1. analyze_diff with base_ref="main" — See all changes with pagination
  2. get_callers — Check impact of modified functions (max depth 3)
  3. validate — Run quality checks on changed files
  4. lint — Auto-detect and run linters with fix mode

Before Modifying Code

Understand impact before making changes:

  1. search — Find the function to modify (hybrid mode)
  2. get_callers — See what depends on it (up to 50 callers)
  3. find_duplicates — Check for similar code to update
  4. validate — Check current complexity before changes

Codebase Health Audit

Assess code quality across the repository:

  1. get_overview — Get module list and risk breakdown
  2. validate with module — Check complexity per module (max 500 symbols)
  3. find_duplicates — Identify code duplication (max 200 clusters)
  4. lint — Run 26+ linters across 16 languages
  5. test — Detect and run available test frameworks

Performance & Optimization

Optimize development workflows:

  1. index — Smart refresh with incremental indexing
  2. get_callgraph — Export to SQLite for large analysis (max 2000 edges)
  3. server_status — Check persistent mode and layer status
  4. prep_commit — Semantic commit analysis with metrics

Usage Tips

Start with Context

Always use get_context first when working with a new repository. It provides git status, branch info, and project type in ~200 tokens.

Unified Tools are More Efficient

Tools like search (hybrid mode), analyze (auto-detect), and validate (scope detection) combine multiple operations into one call, saving tokens and round-trips.

Check Impact Before Changes

Use get_callers before modifying functions to understand what code depends on them (max depth 3, up to 50 results) and might break.

Use Hashes from Results

Search results return symbol hashes. Use these directly with get_symbol, get_source (batch up to 20), or get_callers instead of re-searching.

Pagination for Large Results

Use pagination with analyze_diff (limit/offset), find_duplicates (max 200 clusters), and get_callgraph (max 2000 edges) for better performance.

Smart Index Management

The index tool uses smart refresh by default - only rebuilds if stale. Use force=true for complete regeneration or enable incremental indexing for large codebases.