InSawyerSteps/Kinesis_Multitools

Kinesis Multitools

Kinesis Multitools is a robust, extensible MCP server for IDE-integrated code intelligence, semantic code search, and canonical code pattern management. Built for reliability and security, it enables both developers and AI agents to analyze, search, and interact with codebases efficiently—while remaining open to new tool ideas from the community.

Key Features

• Modern FastMCP Backend:
  • Uses fastmcp==2.9.2 for maximum performance and compatibility (see requirements.txt).
• Supported MCP Tools:
  • index_project_files: Incremental semantic indexing of project files for search.
  • search: Multi-modal codebase search (keyword, regex, semantic, ast, references, similarity, task_verification.
  • cookbook_multitool: Unified tool for capturing and searching canonical code patterns.
  • get_snippet: Extract a precise code snippet from a file by function, class, or line range. Supports extracting the full source of a named function or class (using AST), or any arbitrary line range. Returns a structured status, snippet content, and message. See below for usage details.
  • introspect: Multi-modal code/project introspection multitool for fast, read-only analysis of code and config files. Supports modes for config file reading, structural outline, file statistics, and deep inspection of a function or class. Returns structured results for each mode. See below for usage details.
  • File read/list utilities: Safe listing and reading of project files.
  • anchor_multitool: Project root management (modes: drop, list, remove, rename). Persist external project roots across restarts.
• Reliable by Design: All tools run in isolated processes with hard timeouts, preventing hangs and ensuring the server remains responsive.
• Incremental Indexing: Only changed files are re-embedded, making semantic search fast and efficient.
• Secure & Sandboxed: All file operations are validated to ensure they remain within the configured project root.
• Extensible: A development guide (tooldevguide.md) provides a blueprint for adding new capabilities.

Installation (Windows)

Follow these steps exactly. PyTorch must match your local CUDA and Python versions, and Python 3.13 may require Rust for libcst.

1. Create and activate a virtual environment

# From project root
py -3 -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip setuptools wheel

2. Detect your CUDA version

nvidia-smi
# Note the "CUDA Version" shown (e.g., 12.6, 12.8, 13.0)
# PyTorch provides wheels for specific CUDA toolkits; pick the closest supported (cu118, cu126, cu128)

3. Install PyTorch matching your CUDA and Python

• Visit https://pytorch.org/get-started/previous-versions/ and choose a version that supports your Python (3.12 or 3.13).
• Common index URLs:
  • CUDA 11.8 → https://download.pytorch.org/whl/cu118
  • CUDA 12.6 → https://download.pytorch.org/whl/cu126
  • CUDA 12.8 → https://download.pytorch.org/whl/cu128
  • CPU only → https://download.pytorch.org/whl/cpu

Examples:

# CUDA 12.8, Python 3.13 example
python -m pip install torch==2.7.1 --index-url https://download.pytorch.org/whl/cu128

# CPU-only example
python -m pip install torch==2.7.1 --index-url https://download.pytorch.org/whl/cpu

4. Python 3.13 users: install Rust for libcst (or use Python 3.12) On Python 3.13, libcst often builds from source (no prebuilt wheel) and requires Rust.

Install Rust (PowerShell):

winget install --id Rustlang.Rustup -e --source winget
$env:PATH = "$env:USERPROFILE\.cargo\bin;$env:PATH"
rustc --version

If you prefer not to install Rust, recreate the venv with Python 3.12 instead.

5. Install remaining dependencies (exclude torch)

# Filter out comments and the 'torch' line into a temp file
Get-Content requirements.txt | Where-Object { $_ -notmatch "^\s*#" -and $_ -notmatch "^\s*torch\b" } | Set-Content requirements.no_torch.txt
python -m pip install -r requirements.no_torch.txt

6. Configure your MCP client (Windsurf example) Add to your mcp_config.json:

"kinesis_multitools": {
  "command": "C:\\Projects\\MCP Server\\.venv\\Scripts\\fastmcp.exe",
  "args": [
    "run",
    "C:\\Projects\\MCP Server\\src\\toolz.py",
    "--transport", "stdio"
  ],
  "env": {},
  "disabled": false
}

7. Run and verify

• Launch via your MCP client (e.g., Windsurf). It should start: fastmcp run src/toolz.py --transport stdio.
• Then from your client tools:
  • Drop anchor (register root):

    { "tool": "anchor_multitool", "args": { "mode": "drop", "path": "C:\\Projects\\MCP Server", "project_name": "MCP-Server" } }
    

  • Index project for semantic search:

    { "tool": "index_project_files", "args": { "project_name": "MCP-Server" } }
    

Troubleshooting

• Torch wheel not found: Verify Python version and use the correct index URL (cu118/cu126/cu128/cpu). Use the "Previous Versions" page to find a supported combo.
• libcst build error on Python 3.13: Install Rust (rustup) or use Python 3.12.
• fastmcp not found: Ensure you're using .venv's interpreter: .\.venv\Scripts\activate. Reinstall fastmcp if needed: python -m pip install fastmcp.

Windsurf IDE Configuration

Configure the MCP server in your mcp_config.json:

"kinesis_multitools": {
  "command": "C:\\Projects\\MCP Server\\.venv\\Scripts\\fastmcp.exe",
  "args": [
    "run",
    "C:\\Projects\\MCP Server\\src\\toolz.py",
    "--transport", "stdio"
  ],
  "env": {},
  "disabled": false
}

Note: Ensure the command path points to the correct fastmcp.exe in your .venv.

Usage

Run the MCP server via FastMCP (stdio transport):

fastmcp run src/toolz.py --transport stdio

Notes:

• The server is designed to be launched by an MCP client (e.g., Windsurf) over stdio.
• Direct python src/toolz.py is not the supported entrypoint for serving tools.
• HTTP mode is not provided by default. If you need HTTP, wrap the FastMCP server yourself.

Supported Tools

• index_project_files: Incremental semantic indexing for search.
• search: Multi-modal codebase search (keyword, regex, semantic, ast, references, similarity, task_verification).
• cookbook_multitool: Unified tool for capturing and searching canonical code patterns.
• get_snippet: Extract by function/class/lines.
• introspect: Config/outline/stats/inspect.
• anchor_multitool: Manage project roots (drop/list/remove/rename) and persist across restarts.
• File read/list utilities.

Removed tools:

• The legacy analyze and edit tools have been removed for stability. Only the tools above are supported in this release.

For details on tool usage and extension, see tooldevguide.md.

Canonical Patterns in the Cookbook

The following key patterns from src/toolz.py are available in the project Cookbook for rapid reuse and code consistency. Use the cookbook_multitool to search for or add these patterns to new projects:

If you implement a new utility or multitool that solves a general problem (e.g., logging, config loading, error formatting), consider adding it to the Cookbook for future reuse.

Indexing the Project

Embedding‑based search modes (semantic, similarity, task_verification) require a FAISS vector index. The index is stored in a hidden folder under the project root. If the index is missing, these modes will return an error asking you to run index_project_files first.

Indexing is incremental: unchanged files reuse existing vectors; only added/modified files are re‑embedded.

Invoke the tool from your MCP client:

{
  "tool": "index_project_files",
  "args": { "project_name": "MCP-Server" }
}

Example response:

{
  "status": "success",
  "message": "Project 'MCP-Server' indexed incrementally.",
  "files_scanned_and_included": 150,
  "unchanged_files": 140,
  "updated_files": 10,
  "deleted_files": 0,
  "total_chunks_indexed": 1250,
  "indexing_duration_seconds": 15.75
}

Searching the Codebase

Call the search tool with the desired search_type and parameters.

Semantic search example:

{
  "tool": "search",
  "args": {
    "search_type": "semantic",
    "query": "how does the server manage timeouts on Windows?",
    "project_name": "MCP-Server",
    "params": { "max_results": 5 }
  }
}

AST search for a function definition:

{
  "tool": "search",
  "args": {
    "search_type": "ast",
    "query": "unified_search",
    "project_name": "MCP-Server",
    "params": { "target_node_type": "function" }
  }
}

Other supported search_type values: keyword, regex, references, similarity, task_verification.

Tip: narrow scope with params.includes (glob patterns) and set params.max_results to limit output.

Windows Reliability Notes

• Tools are decorated for strict timeouts. On Windows, thread‑based timeouts are used where process isolation is unsafe for certain workloads; on POSIX, process‑based timeouts are used.
• Decorator order matters for Windows: @mcp.tool(...) must be the outermost decorator. This repository follows that rule across all tools.
• Enable verbose search diagnostics by setting MCP_DEBUG_SEARCH=1 in the environment before launching the server.

Roadmap

Roadmap & Community Involvement:

We welcome suggestions and contributions for new tools! If you have an idea for a code intelligence, search, or automation tool that would benefit the community, please open an issue or submit a pull request.

• index_project_files: Incremental semantic indexing of project files for search.
• search: Multi-modal codebase search (keyword, regex, semantic, ast, references, similarity, task_verification.
• cookbook_multitool: Unified tool for capturing and searching canonical code patterns (see below).
• get_snippet: Extract a function, class, or line range from any project file. See below for details.
• introspect: Multi-modal code/project introspection for config, outline, stats, and inspect. See below for details.
• File read/list utilities.

Code Cookbook Multitool

The cookbook_multitool is a unified endpoint for capturing and searching canonical code patterns ("golden patterns") across multiple languages. It replaces the older add_to_cookbook and find_in_cookbook tools.

Purpose

• Add a pattern's source and metadata to the project cookbook (supports Python, JavaScript/TypeScript, HTML, JSON, and plain text).
• Find patterns by name, description, or function name, optionally filtering by language.

Multi-language add options

Use /cookbook_multitool with mode: "add". You can add patterns via one of the following strategies:

• File + function/class name (language auto-detected by extension, with override):

{
  "mode": "add",
  "pattern_name": "secure_path_validator",
  "file_path": "C:/Projects/MCP Server/src/toolz.py",
  "function_name": "_is_safe_path",
  "description": "Ensures a given path stays within allowed project roots.",
  "language": "python"
}

• JavaScript/TypeScript function extraction (regex + brace balancing):

{
  "mode": "add",
  "pattern_name": "fetch_with_retry",
  "file_path": "C:/Projects/app/src/utils.ts",
  "function_name": "fetchWithRetry",
  "description": "Wrapper around fetch with exponential backoff.",
  "language": "typescript"
}

• HTML: extract from

{
  "mode": "add",
  "pattern_name": "form_validate_handler",
  "file_path": "C:/Projects/site/index.html",
  "start_marker": "<!-- VALIDATE_START -->",
  "end_marker": "<!-- VALIDATE_END -->",
  "description": "Client-side validation handler embedded in script block.",
  "language": "html"
}

• JSON/Text: store a snippet directly or via line markers:

{
  "mode": "add",
  "pattern_name": "pytest_config",
  "code_snippet": "{\n  \"pytest\": { \"addopts\": \"-q\" }\n}",
  "description": "Minimal pytest JSON config snippet.",
  "language": "json"
}

Find with optional language filter

{
  "mode": "find",
  "query": "secure path",
  "language": "python"
}

Response

• On success, returns a status and message (for add), or a list of matching patterns (for find).
• Stored metadata includes language, extraction_strategy, and a locator describing how the snippet was extracted (e.g., function name, markers, or direct snippet).
• Cookbook patterns are stored as JSON files in .project_cookbook/ in the project root.

See tooldevguide.md for full schema, edge cases, and additional examples.

get_snippet Tool

The get_snippet tool extracts a precise code snippet from a file by function, class, or line range.

Capabilities:

• Extract the full source of a named function (including decorators and signature)
• Extract the full source of a named class (including decorators and signature)
• Extract an arbitrary range of lines from any text file

Arguments:

• file_path (str): Absolute path to the file to extract from. Must be within the project root.
• mode (str): Extraction mode. One of:
  • function: Extract a named function by its name.
  • class: Extract a named class by its name.
  • lines: Extract a specific line range.
• name (str, optional): Required for function and class modes. The name of the function or class to extract.
• start_line (int, optional): Required for lines mode. 1-indexed starting line.
• end_line (int, optional): Required for lines mode. 1-indexed ending line (inclusive).

Returns:

• status (str): 'success', 'error', or 'not_found'
• snippet (str, optional): The extracted code snippet (if found)
• message (str): Human-readable status or error message

Usage Examples:

{
  "file_path": "/project/src/foo.py",
  "mode": "function",
  "name": "my_func"
}

{
  "file_path": "/project/src/foo.py",
  "mode": "lines",
  "start_line": 10,
  "end_line": 20
}

introspect Tool

The introspect tool is a multi-modal code/project introspection multitool for fast, read-only analysis of code and config files.

Modes:

• config: Reads project configuration files (pyproject.toml or requirements.txt).
  • Args: config_type ('pyproject' or 'requirements').
  • Returns: For 'pyproject', the full TOML text. For 'requirements', a list of package strings.
• outline: Returns a high-level structural map of a Python file: all top-level functions and classes (with their methods).
  • Args: file_path (str)
  • Returns: functions (list), classes (list of {name, methods})
• stats: Calculates basic file statistics: total lines, code lines, comment lines, file size in bytes.
  • Args: file_path (str)
  • Returns: total_lines (int), code_lines (int), comment_lines (int), file_size_bytes (int)
• inspect: Provides details about a single function or class in a file: name, arguments/methods, docstring.
  • Args: file_path (str), function_name (str, optional), class_name (str, optional)
  • Returns: type ('function' or 'class'), name, args/methods, docstring

Arguments:

• mode (str): One of 'config', 'outline', 'stats', 'inspect'.
• file_path (str, optional): Path to the file for inspection (required for all except config).
• config_type (str, optional): 'pyproject' or 'requirements' for config mode.
• function_name (str, optional): Name of function to inspect (for 'inspect' mode).
• class_name (str, optional): Name of class to inspect (for 'inspect' mode).

Returns:

• status (str): 'success', 'error', or 'not_found'
• message (str): Human-readable status or error message
• Mode-specific fields:
  • config: config_type, content (str) or packages (list)
  • outline: functions (list), classes (list of {name, methods})
  • stats: total_lines (int), code_lines (int), comment_lines (int), file_size_bytes (int)
  • inspect: type, name, args/methods, docstring

Usage Examples:

{
  "mode": "outline",
  "file_path": "/project/src/foo.py"
}

{
  "mode": "inspect",
  "file_path": "/project/src/foo.py",
  "function_name": "my_func"
}

{
  "mode": "config",
  "config_type": "requirements"
}

License

This project is licensed under the MIT License. See the file for details.