MCP Tools Reference

The CIAK MCP server exposes 7 tools that AI assistants can use to search, analyze, and understand your codebase. The MCP server runs locally in your IDE and communicates with the CIAK cloud behind the scenes. Each tool is available via the Model Context Protocol (MCP).

All tools accept a project_path parameter that points to the root of your CIAK-initialized project (the directory containing .ciak/config.toml).

Search tools (search_code, analyze_symbols, vector_search, optimize_context) support Query Enhancement — automatic synonym expansion, acronym resolution, and intent classification to improve search recall. This is enabled by default and can be disabled per-request with enhance_query: false.

For text-based symbol search tools (search_code, analyze_symbols), CIAK also applies default path-aware ranking priors (boost implementation paths, demote test/spec/sample paths). You can tune this in [ranking] config.

Input and Output Conventions

• Example input blocks below show the tool arguments you pass to the MCP tool (not the full JSON-RPC envelope used by some clients).
• Example output (partial) blocks show the tool result payload and are intentionally truncated to highlight the most useful fields.
• Exact formatting can vary by AI client, but the field names and shapes below reflect what users should expect conceptually.

---

search_code

Search code using natural language queries with intent classification and relevance scoring.

Best for: Finding code by describing what it does in plain English.

Parameters

Parameter	Type	Required	Default	Description
query	string	✅	—	Natural language query to search for code
project_path	string	✅	—	Absolute path to your CIAK project
limit	integer	—	10	Maximum number of results
with_context	boolean	—	false	Include code snippets with surrounding context
group_results	boolean	—	false	Group results by symbol type (Functions, Classes, etc.)
include_ranking_factors	boolean	—	false	Include per-result ranking diagnostics (base_score, path adjustment, anchor bonus, test penalty, final score)
enhance_query	boolean	—	true	Enable query enhancement (synonym expansion, intent classification)

Example Input

{
  "query": "function that handles user authentication",
  "project_path": "/home/user/my-project",
  "limit": 10,
  "with_context": true,
  "group_results": true
}

Example Output (partial)

{
  "results": [
    {
      "file_path": "src/auth/service.ts",
      "line_number": 42,
      "content": "async function authenticateUser(token: string) { ... }",
      "relevance_score": 0.94,
      "ranking_factors": {
        "base_score": 0.79,
        "path_boost_demotion": 0.09,
        "anchor_bonus": 0.06,
        "test_penalty": 0.0,
        "final_score": 0.94
      },
      "symbol_type": "function",
      "enhanced_code_context": "..."
    }
  ],
  "ranking_diagnostics": {
    "ranking_profile": "unified_symbol_search_v1",
    "scoring_version": "unified_search_rank_v1",
    "factors_enabled": {
      "base_score": true,
      "path_boost_demotion": true,
      "anchor_bonus": true,
      "test_penalty": true,
      "final_score": true
    }
  },
  "grouped_results": {
    "Functions": [
      {
        "file_path": "src/auth/service.ts",
        "line_number": 42,
        "relevance_score": 0.94
      }
    ]
  }
}

Response

Returns a list of matching code results with:

• file_path and line_number for each match
• content — the code snippet or signature
• relevance_score — how well the result matches (0.0–1.0)
• ranking_factors — optional explainability block for ranking (returned when include_ranking_factors is true)
• base_score — normalized relevance before path priors
• path_boost_demotion — net adjustment from boost/demote path priors
• anchor_bonus — bonus from anchor-term file matching
• test_penalty — explicit negative adjustment for test/spec paths when demoted
• final_score — final score used for ordering
• ranking_diagnostics — top-level scoring metadata for the whole response
• ranking_profile — active ranking profile identifier
• scoring_version — scorer version tag to compare behavior across environments
• factors_enabled — which factor categories are currently active in scoring
• symbol_type — function, class, method, etc.
• enhanced_code_context — surrounding code lines (when with_context is true)
• grouped_results — results organized by category (when group_results is true)

ranking_diagnostics is independent of with_context and group_results.
include_ranking_factors only controls per-result ranking_factors emission.

---

analyze_symbols

Search and analyze code symbols with filtering and relationship information.

Best for: Finding specific functions, classes, or interfaces and understanding their relationships.

Parameters

Parameter	Type	Required	Default	Description
query	string	✅	—	Query to search for symbols
project_path	string	—	—	Absolute path to your CIAK project
symbol_types	string[]	—	all	Filter by type: function, class, method, type, interface, variable, constant
languages	string[]	—	all	Filter by programming language
limit	integer	—	20	Maximum number of results
path_patterns	string[]	—	—	Glob patterns for path filtering (e.g., src/**/*.rs, !tests/**)
parent_class	string	—	—	Filter by parent class name
implements	string	—	—	Filter by implemented interface
visibility	string[]	—	—	Filter by visibility: public, private, protected, internal, package, default
enhance_query	boolean	—	true	Enable query enhancement (synonym expansion, intent classification)

Example Input

{
  "query": "authenticate",
  "project_path": "/home/user/my-project",
  "symbol_types": ["function", "method"],
  "languages": ["typescript"],
  "path_patterns": ["src/**/*.ts", "!tests/**"],
  "visibility": ["public"]
}

Example Output (partial)

{
  "results": [
    {
      "name": "authenticateUser",
      "symbol_type": "method",
      "file_path": "src/auth/service.ts",
      "line_number": 88,
      "signature": "public async authenticateUser(credentials: LoginDto): Promise<User>",
      "documentation": "Validates credentials and returns the user profile.",
      "visibility": "public",
      "relationships": {
        "implements": [],
        "uses": ["TokenService", "UserRepository"]
      }
    }
  ],
  "filters_applied": {
    "symbol_types": ["function", "method"],
    "languages": ["typescript"],
    "path_patterns": ["src/**/*.ts", "!tests/**"],
    "visibility": ["public"]
  }
}

Response

Returns matching symbols with:

• name, symbol_type, file_path, line_number
• signature — the full function/class signature
• documentation — any doc comments
• relationships — how this symbol relates to others (extends, implements, imports)
• visibility — public, private, etc.
• filters_applied — summary of which filters were used

---

vector_search

Perform semantic similarity search using embeddings. Finds code that is conceptually similar to your query, even if it doesn't share the same keywords.

Best for: Finding code by meaning rather than exact text matches. Requires embeddings to be generated during scan (ciak scan --embeddings).

Parameters

Parameter	Type	Required	Default	Description
query	string	✅	—	Semantic search query. For best results, format as <type> <name> <language>
project_path	string	✅	—	Absolute path to your CIAK project
similarity_threshold	number	—	0.7	Minimum similarity score (0.0–1.0)
limit	integer	—	10	Maximum number of results
symbol_types	string[]	—	all	Filter by symbol type: class, interface, function, method, variable, constant, enum, type
enable_type_boost	boolean	—	true	Boost scores for high-value symbols (classes, functions) over noise (variables, imports)
language	string	—	—	Pre-filter: narrow to a specific language before searching
path_patterns	string[]	—	—	Pre-filter: glob patterns applied before vector similarity
modified_within_days	integer	—	—	Pre-filter: only search files modified within N days
enhance_query	boolean	—	true	Enable query enhancement (synonym expansion, intent classification)

Query Tips

The stored embeddings use the format <type> <name> lang:<lang> context:<code>. For best results:

• ✅ "method insertAuthorAudience typescript" — includes type + name + language
• ✅ "authentication login jwt" — descriptive terms work well
• ❌ "insertAuthorAudience" — symbol name alone may not match well

Example Input

{
  "query": "class authentication guard typescript",
  "project_path": "/home/user/my-project",
  "similarity_threshold": 0.7,
  "symbol_types": ["class", "function", "method"],
  "enable_type_boost": true,
  "language": "typescript"
}

Example Output (partial)

{
  "results": [
    {
      "file_path": "src/auth/auth.guard.ts",
      "line_number": 12,
      "content": "export class AuthGuard implements CanActivate { ... }",
      "similarity_score": 0.91,
      "code_context": "...",
      "symbol_type": "class"
    }
  ],
  "threshold_used": 0.7
}

Response

Returns semantically similar code with:

• content — the matched code
• file_path and line_number
• similarity_score — how semantically close the result is (0.0–1.0)
• code_context — surrounding code snippet
• threshold_used — the similarity threshold that was applied

---

optimize_context

Generate optimized code context using multiple optimization strategies. Useful for gathering the most relevant code context for a given task within a token budget.

Best for: Building focused context windows for AI-assisted coding tasks.

Parameters

Parameter	Type	Required	Default	Description
query	string	✅	—	Description of what context you need
project_path	string	✅	—	Absolute path to your CIAK project
max_tokens	integer	—	8000	Maximum tokens in the optimized context
strategy	string	—	hybrid	Optimization strategy (see below)
path_patterns	array<string>	—	—	Include glob patterns (for example packages/core/**)
exclude_patterns	array<string>	—	—	Exclude glob patterns (for example **/tests/**)
symbol_types	array<string>	—	—	Restrict results to symbol types (for example method, class)
prefer_implementation_over_tests	boolean	—	false	Demote tests/specs and prefer implementation files
include_diagnostics	boolean	—	false	Include per-file ranking explanations in metadata
enhance_query	boolean	—	true	Enable query enhancement (synonym expansion, intent classification)

Strategies

Strategy	Description
vector	Semantic similarity — finds code closest in meaning to the query
text	Traditional text search
hybrid	Combines vector and text search (recommended default)
dependency	Follows code relationships and dependencies
recency	Prioritizes recently modified files
adaptive	Automatically selects the best strategy

Legacy names semantic and combined are also supported.

Example Input

{
  "query": "implement JWT token validation middleware",
  "project_path": "/home/user/my-project",
  "max_tokens": 8000,
  "strategy": "hybrid",
  "path_patterns": ["src/auth/**"],
  "exclude_patterns": ["**/tests/**", "**/*.spec.ts"],
  "symbol_types": ["class", "method"],
  "prefer_implementation_over_tests": true,
  "include_diagnostics": true
}

Example Output (partial)

{
  "optimized_context": "File: src/auth/jwt-middleware.ts\\n...truncated...",
  "strategy_used": "hybrid",
  "token_count": 6124,
  "metadata": {
    "files_analyzed": 23,
    "files_included": 7,
    "processing_time_ms": 184,
    "diagnostics": {
      "src/auth/jwt-middleware.ts": "base=0.941;symbol_bonus=0.080;...;final=1.021"
    }
  }
}

Response

Returns:

• optimized_context — the assembled code context, ready to use
• strategy_used — which strategy was actually applied
• token_count — number of tokens in the context
• metadata — relevance scores, processing time, files analyzed, and optional diagnostics

---

get_related_context

Discover and rank all files related to a target file through dependencies, imports, and usage relationships.

Best for: Understanding the full context around a file — what it depends on and what depends on it.

Parameters

Parameter	Type	Required	Default	Description
target	string	✅	—	Target file path or symbol name
project_path	string	✅	—	Absolute path to your CIAK project
max_files	number	—	10	Maximum number of related files to return
include_tests	boolean	—	false	Include test files in results
relevance_threshold	number	—	0.3	Minimum relevance score (0.0–1.0)
max_depth	number	—	3	Maximum dependency traversal depth

Example Input

{
  "target": "src/auth/service.ts",
  "project_path": "/home/user/my-project",
  "max_files": 15,
  "include_tests": false,
  "relevance_threshold": 0.3,
  "max_depth": 3
}

Example Output (partial)

{
  "related_files": [
    {
      "file_path": "src/auth/controller.ts",
      "language": "typescript",
      "relevance_score": 0.93,
      "relationship_type": "uses"
    },
    {
      "file_path": "src/auth/token.service.ts",
      "language": "typescript",
      "relevance_score": 0.88,
      "relationship_type": "imports"
    }
  ],
  "summary": {
    "target": "src/auth/service.ts",
    "max_depth_used": 3,
    "include_tests": false
  }
}

Response

Returns related files ranked by relevance, including:

• File path and language
• Relevance score
• Relationship type (imports, extends, implements, uses, etc.)
• Summary statistics

---

analyze_relationships

Perform comprehensive relationship analysis including dependency graphs, pattern detection, quality metrics, impact analysis, and circular dependency detection.

Best for: Understanding how a symbol or file connects to the rest of the codebase, detecting architectural patterns, and assessing change impact.

Parameters

Parameter	Type	Required	Default	Description
target	string	✅	—	Symbol name (e.g., AuthService) or file path (e.g., src/auth/service.ts)
project_path	string	✅	—	Absolute path to your CIAK project
mode	string	—	standard	Analysis depth mode (see table below)
max_depth	number	—	—	Override mode's default depth (1–20)
include_tests	boolean	—	false	Include test files in analysis
timeout_seconds	number	—	30	Analysis timeout in seconds (1–60)
enable_cache	boolean	—	true	Enable caching of results
cache_ttl_seconds	number	—	3600	Cache time-to-live in seconds
visualization_format	string	—	json	Output format: json, mermaid, ascii, dot
max_nodes	number	—	—	Hard cap for returned graph participants and relationships after filters are applied. Lower = faster. Defaults: quick=30, standard=100, deep=200
call_chain_max_depth	number	—	3	Maximum call-chain traversal depth
call_chain_max_paths	number	—	15	Maximum number of call paths to collect
fetch_source_context	boolean	—	false	Fetch source code snippet for each dependency node (1 DB query per node — enable only for small graphs)
entry_points_detection	boolean	—	false	Run full entry-point detection with a DB lookup per pattern (disable for speed; enable for precise entry-point resolution)
include_filter_diagnostics	boolean	—	false	Include sampled exclusion examples in filter_diagnostics.sampled_exclusion_examples for debugging
include_builtins	boolean	—	false	Include builtin and standard-library relationships
exclude_builtins	boolean	—	false	Exclude builtin and standard-library relationships
edge_types	string[]	—	all	Restrict output to normalized edge categories: import, call, inheritance, member_use, type_reference
only_critical_chain	boolean	—	false	Return compact target-centric call-chain output for route tracing
exclude_synthetic_nodes	boolean	—	false	Suppress synthetic utility artifacts (for example map, push, log)

Analysis Modes

Mode	Depth	Pattern Detection	Quality Metrics	Impact Analysis	Call Chains	Notes
quick	1	❌	❌	❌	❌	Fastest — immediate dependencies only
standard	2	❌	✅	✅	✅	Default — balanced speed and detail
deep	3	✅	✅	✅	✅	Slower — full pattern detection
critical	4	✅	✅	✅	✅	Most detailed — use on small graphs

Performance

Prefer quick or standard on large projects to avoid timeouts. Use --max-nodes to cap graph size when needed.

Hard-cap semantics (max_nodes)

When max_nodes is set (or inherited from mode defaults), the returned graph is strictly capped:

• Filtering is applied first (include_tests, builtin/stdlib filtering, and edge_types) so excluded items do not consume cap budget.
• Truncation is deterministic for the same input (confidence + proximity + stable tie-break).
• The response includes cap_metadata so you can confirm cap behavior:
  • cap_requested
  • cap_applied
  • cap_reached
  • dropped_node_count

Synthetic-node suppression rules

exclude_synthetic_nodes uses language packs from:

• src/rust/common/src/relationship_analysis/builtin_packs/javascript_typescript.toml
• src/rust/common/src/relationship_analysis/builtin_packs/rust.toml
• src/rust/common/src/relationship_analysis/builtin_packs/python.toml

To support more languages, add synthetic utility rules to the appropriate pack instead of hardcoding detector logic.

Filter diagnostics block

analyze_relationships now returns a response-level filter_diagnostics object with machine-readable exclusion accounting:

• filters_applied — active filter names (tests, builtins, synthetic, edge_type_mismatch, depth_pruned, cap_pruned)
• excluded_count — total exclusions across all buckets
• exclusion_buckets — per-bucket counts:
  • tests
  • builtins
  • synthetic
  • edge_type_mismatch
  • depth_pruned
  • cap_pruned
• returned_size — node counts:
  • nodes_before_filter
  • nodes_after_filter
  • nodes_returned
• sampled_exclusion_examples — optional bounded examples (returned when include_filter_diagnostics: true)

Visualization Formats

Format	Description
json	Structured data (default) — best for programmatic use
mermaid	Mermaid diagram syntax — paste into any Mermaid renderer
ascii	Terminal-friendly tree — readable inline
dot	Graphviz DOT format — render with dot, fdp, etc.

Example Input

{
  "target": "AuthService",
  "project_path": "/home/user/my-project",
  "mode": "standard",
  "include_tests": false,
  "include_filter_diagnostics": true,
  "visualization_format": "mermaid",
  "only_critical_chain": false,
  "exclude_synthetic_nodes": true
}

Performance Tuning Example

For large codebases where the default may be slow:

{
  "target": "UserRepository",
  "project_path": "/home/user/my-project",
  "mode": "quick",
  "max_nodes": 50,
  "call_chain_max_depth": 2,
  "call_chain_max_paths": 5,
  "timeout_seconds": 15
}

Example Output (partial)

{
  "graph": {
    "direct_dependencies": [
      { "name": "UserRepository", "type": "class", "relationship": "uses" }
    ],
    "dependents": [
      { "name": "AuthController", "type": "class", "relationship": "uses" }
    ]
  },
  "quality_metrics": {
    "coupling_score": 0.42,
    "cohesion_score": 0.81,
    "maintainability_index": 78
  },
  "impact_analysis": {
    "direct_impact_count": 4,
    "indirect_impact_count": 11,
    "impact_score": 0.67
  },
  "visualization": "graph TD\\n  AuthController --> AuthService\\n  AuthService --> UserRepository",
  "performance": {
    "total_time_ms": 236,
    "node_count": 24,
    "edge_count": 39
  },
  "cap_metadata": {
    "cap_requested": 50,
    "cap_applied": 50,
    "cap_reached": false,
    "dropped_node_count": 0
  },
  "filter_diagnostics": {
    "filters_applied": ["tests", "builtins", "synthetic", "edge_type_mismatch"],
    "excluded_count": 8,
    "exclusion_buckets": {
      "tests": 2,
      "builtins": 3,
      "synthetic": 1,
      "edge_type_mismatch": 2,
      "depth_pruned": 0,
      "cap_pruned": 0
    },
    "returned_size": {
      "nodes_before_filter": 41,
      "nodes_after_filter": 33,
      "nodes_returned": 33
    },
    "sampled_exclusion_examples": [
      {
        "reason_code": "builtins",
        "dependency_type": "direct_dependency",
        "target_id": "src/auth/service.ts:parseInt"
      }
    ]
  },
  "from_cache": false
}

Response

Returns comprehensive analysis including:

• graph — dependency graph with direct dependencies, dependents, inheritance chain, interface implementations, data flow, and module coupling
• patterns — detected architectural patterns (Strategy, Factory, Observer, etc.) with confidence scores — only in deep and critical modes
• quality_metrics — coupling score, cohesion score, stability index, abstractness, maintainability index, and quality flags — available in standard, deep, and critical modes
• impact_analysis — direct and indirect impact lists with an impact score — available in standard, deep, and critical modes
• call_chains — longest call chains, complex paths, average chain length, entry-to-target paths, and detected entry points — available in standard, deep, and critical modes
• call_chains.critical_chain — compact ordered route to the target; emphasized when only_critical_chain: true
• cap_metadata — hard-cap accounting (cap_requested, cap_applied, cap_reached, dropped_node_count)
• filter_diagnostics — machine-readable filter/exclusion accounting, bucketed by reason, with optional sampled examples
• circular_dependencies — list of detected dependency cycles (always computed)
• visualization — graph rendered in the requested format
• performance — timing breakdown per analysis phase (graph build, pattern detection, quality metrics, etc.) and node/edge counts
• from_cache — whether the result was served from cache

---

search_knowledge

Query the technical knowledge base with entry type filtering and fuzzy matching.

Best for: Looking up domain-specific terms, acronyms, and synonyms that have been added to the knowledge base.

Parameters

Parameter	Type	Required	Default	Description
query	string	✅	—	Search query for the knowledge base
project_path	string	—	—	Absolute path to your CIAK project
entry_types	string[]	—	all	Filter by type: technical_term, synonym, acronym
fuzzy_matching	boolean	—	true	Enable fuzzy matching for partial terms

Example Input

{
  "query": "JWT",
  "project_path": "/home/user/my-project",
  "entry_types": ["acronym", "technical_term"],
  "fuzzy_matching": true
}

Example Output (partial)

{
  "results": [
    {
      "term": "JWT",
      "definition": "JSON Web Token - a compact token format for authentication",
      "entry_type": "acronym",
      "confidence_score": 1.0,
      "related_terms": ["authentication", "OAuth"]
    }
  ]
}

Response

Returns matching knowledge entries with:

• Term, definition, and category
• Entry type (technical_term, synonym, acronym)
• Confidence score
• Related terms and synonyms

---

Common Error Output (partial)

Most tools return a structured error payload when something goes wrong (invalid parameters, missing project/database, timeouts, etc.):

{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "project_path must point to a CIAK-initialized project",
    "details": {
      "project_path": "/home/user/my-project"
    }
  }
}