Copyright (c) 2025 Chris Drake. All rights reserved.
An SSE-transport local MCP server with pluggable tool ecosystem.
Server domain: https://mcp.aurafriday.com/sse
Available Tools
cards
Parameters Schema
{
"properties": {
"input": {
"type": "object",
"description": "All tool parameters are passed in this single dict. Use {\"input\":{\"operation\":\"readme\"}} to get full documentation, parameters, and an unlock token."
}
},
"required": [],
"type": "object"
}
A shuffled deck of cards.
- Use this when you need to determine participant ordering, play games, or have other use-cases that can be solved by drawing and comparing cards at random.
Card-based participant ordering system using standard deck of cards.
## Usage-Safety Token System
This tool uses an hmac-based token system to ensure callers fully understand all details of
using this tool, on every call. The token is specific to this installation, user, and code version.
Your tool_unlock_token for this installation is: 134f96fe
You MUST include tool_unlock_token in the input dict for all operations.
## Input Structure
All parameters are passed in a single 'input' dict:
1. For this documentation:
{
"input": {"readme": true}
}
2. For operations:
{
"input": {
"operation": "get_cards",
"participant_id": "hostname:username:path",
"expected_participants": 2,
"num_cards": 1,
"wait": true,
"tool_unlock_token": "134f96fe"
}
}
## Operations
- get_cards: Get card(s) for a participant
- get_order: Get current participant ordering (highest card first)
- get_my_order: Get specific participant's position (only when complete)
- get_game_status: Show game state information including participant list, remaining cards, and slots
- list_active_games: Show all active games
- reset_game: Force reset a game's state (use when participants are missing/inactive)
## Important Usage Notes
**Wait Functionality:**
When calling get_cards, if you need to know your ranking/position immediately
(e.g., if you need to respond with "I am in 1st place"), you MUST set wait=true.
Otherwise, you'll get your card but won't know your final position until all players have joined.
**Participant Identification:**
1. When calling get_cards:
- Provide your ID in format: "hostname:username:path"
- The system automatically assigns you the next available player number
- Example: "myhost:john:project" becomes "myhost:john:project:player_1"
2. For all subsequent operations:
- Use the complete ID returned by get_cards
- This includes your system-assigned player number
**Wait Functionality:**
- Operations support an optional 'wait' parameter
- When wait=True, operation blocks until all expected participants have received cards
- Default timeout of 270s (configurable via wait_timeout parameter)
- Mandatory to use wait=True if immediate position information is needed
- Example: get_cards(..., wait=True) ensures all players have cards when response received
**Card Ordering Rules:**
1. Primary Sort: Card Rank (highest to lowest)
- Ace (highest)
- King, Queen, Jack
- 10 through 2 (descending)
2. Secondary Sort (only as tiebreaker): Suit
- Spades (♠), Hearts (♥), Diamonds (♦), Clubs (♣)
## Examples
```json
// Get cards and wait for all participants
{
"input": {
"operation": "get_cards",
"participant_id": "myhost:john:project",
"expected_participants": 3,
"num_cards": 1,
"wait": true,
"tool_unlock_token": "134f96fe"
}
}
// Get current ordering
{
"input": {
"operation": "get_order",
"game_name": "default",
"expected_participants": 3,
"tool_unlock_token": "134f96fe"
}
}
// Get my specific position (only works when game complete)
{
"input": {
"operation": "get_my_order",
"participant_id": "myhost:john:project:player_1",
"expected_participants": 3,
"tool_unlock_token": "134f96fe"
}
}
// List all active games
{
"input": {
"operation": "list_active_games",
"tool_unlock_token": "134f96fe"
}
}
```
## Notes
- Games are identified by name AND number of expected participants
- Thread-safe for simultaneous access
- State is not persisted across server restarts
- Token changes when tool code is modified, forcing re-reading of documentation
context7
Parameters Schema
{
"properties": {
"input": {
"type": "object",
"description": "All tool parameters are passed in this single dict. Use {\"input\":{\"operation\":\"readme\"}} to get full documentation, parameters, and an unlock token."
}
},
"required": [],
"type": "object"
}
Retrieves up-to-date documentation and code examples for any library.
- Use this when you need current documentation for libraries and frameworks
Context7 MCP - Up-to-date Code Docs For Any Prompt
This tool retrieves up-to-date documentation and code examples for any library directly from Context7.
## Usage-Safety Token System
This tool uses an hmac-based token system to ensure callers fully understand all details of
using this tool, on every call. The token is specific to this installation, user, and code version.
Your tool_unlock_token for this installation is: bca4bcac
You MUST include tool_unlock_token in the input dict for all operations.
## Input Structure
All parameters are passed in a single 'input' dict:
1. For this documentation:
{
"input": {"readme": true}
}
2. For resolve-library-id operation:
{
"input": {
"operation": "resolve-library-id",
"library_name": "library to search for",
"tool_unlock_token": "bca4bcac"
}
}
3. For get-library-docs operation:
{
"input": {
"operation": "get-library-docs",
"context7_compatible_library_id": "library ID from resolve-library-id",
"topic": "optional topic focus",
"tokens": 10000,
"tool_unlock_token": "bca4bcac"
}
}
## Usage Notes
1. You MUST call resolve-library-id first to get a valid Context7-compatible library ID
2. Include the tool_unlock_token in all operations
3. For best results, select libraries based on name match, popularity (stars), snippet coverage, and relevance to use case
4. The tokens parameter determines how much documentation is retrieved (minimum: 10000)
## Examples
```json
# First, resolve the library ID
{
"input": {
"operation": "resolve-library-id",
"library_name": "react",
"tool_unlock_token": "bca4bcac"
}
}
# Then, get the documentation using the returned library ID
{
"input": {
"operation": "get-library-docs",
"context7_compatible_library_id": "facebook/react",
"topic": "hooks",
"tokens": 15000,
"tool_unlock_token": "bca4bcac"
}
}
```
direct_sqlite
Parameters Schema
{
"properties": {
"input": {
"type": "object",
"description": "All tool parameters are passed in this single dict. Use {\"input\":{\"readme\":true}} to get full documentation, parameters, and an unlock token."
}
},
"required": [],
"type": "object"
}
Execute SQLite database commands. Includes semantic similarity search and automatic vector embedding generation.
- Use this when you need to execute SQLite commands or work on tasks that need database and/or semantic searches
Execute SQLite commands and return results in JSON format. Key features:
## Usage-Safety Token System
This tool uses an hmac-based token system to ensure callers fully understand all details of
using this tool, on every call. The token is specific to this installation, user, and code version.
Your tool_unlock_token for this installation is: 21639ee1
You MUST include tool_unlock_token in the input dict for all operations.
## Input Structure
All parameters are passed in a single 'input' dict:
1. For this documentation:
{
"input": {"readme": true}
}
2. For SQL operations:
{
"input": {
"sql": "SELECT * FROM table_name",
"database": ":memory:",
"bindings": {"param": "value"},
"tool_unlock_token": "21639ee1"
}
}
## Authentication Integration:
- All tool calls automatically receive the authenticated username
- Username is available as :authenticated_user parameter in SQL queries
- Useful for user-specific data access and audit trails
## Basic Database Operations:
- Database: Use ':memory:' for temporary storage (persists until server restart, shared between AI instances)
- Or use filename for persistent database with these path options:
* Simple filename (e.g. 'data.db') -> stored in same directory as run_ragtag_sse.py
(typically python/ragtag/run_ragtag_sse.py in the project root)
* Full path (e.g. './data.db' or 'C:\data.db') -> used as-is
* Windows environment variables (e.g. '%APPDATA%\data.db') -> expanded on Windows only
* Home directory (e.g. '~/data.db') -> expanded to user home on all platforms
* Cross-platform app data (e.g. '@appdata/data.db') -> uses appropriate OS location:
- Windows: %APPDATA% (~/AppData/Roaming)
- macOS: ~/Library/Application Support
- Linux: ~/.local/share
- Parameters: SQL command with :param style placeholders (e.g. :name, :value)
- Bindings: Pass values safely using bindings object (e.g. {"name": "test", "value": 123})
## Storage Locations
Database paths can be:
- ':memory:' -> Temporary, shared between AI instances until server restart
- '@user_data/db.sqlite' -> Primary storage (syncs on Windows domain)
- '@user_local/db.sqlite' -> Machine-specific storage (never syncs)
- '@user_cache/db.sqlite' -> Temporary data (system may clear)
- '@user_config/db.sqlite' -> Settings/config data
- '@site_data/db.sqlite' -> Multi-user shared (needs elevation)
- '@temp/db.sqlite' -> System temp (cleared on reboot)
- '/absolute/path/db.sqlite' -> Custom location
- 'db.sqlite' -> Uses @user_data/ by default
## Vector Similarity Search Support:
- Create tables with vector columns:
```sql
CREATE TABLE documents(
id INTEGER PRIMARY KEY,
contents TEXT,
embedding BLOB CHECK(
typeof(embedding) == 'blob'
AND vec_length(embedding) == 3072 -- For Gemini embeddings
)
);
```
- Automatic Embedding Generation:
IMPORTANT: Requires GEMINI_API_KEY environment variable to be set.
Two special binding formats for automatic Gemini embeddings:
1. Reference Another Binding; ALWAYS do this if when the text of the embedding is also stored in the database:
```python
execute_sql(
"INSERT INTO docs(text, embedding) VALUES (:text, vec_f32(:embedding))", # Note: vec_f32() required
bindings={
"text": "Some text to store and embed",
"embedding": {"_embedding_col": "text"} # Uses text from :text binding
}
)
```
2. Direct Text Embedding:
```python
execute_sql(
"INSERT INTO docs(text, embedding) VALUES (:text, vec_f32(:embedding))", # Note: vec_f32() required
bindings={
"text": "Some text to store",
"embedding": {"_embedding_text": "Text to embed"} # Only do this if you're not storing the embedded text in the database.
}
)
```
Similarity Search Examples:
```python
# Basic similarity search
execute_sql(
"""SELECT text, vec_distance_cosine(embedding, vec_f32(:query_vec)) as distance
FROM docs
WHERE vec_distance_cosine(embedding, vec_f32(:query_vec)) < 0.5 -- Range: 0-1, lower is more similar
ORDER BY distance LIMIT 5"""",
bindings={
"query_vec": {"_embedding_text": "Find text similar to this"}
}
)
# Find similar to existing document
execute_sql(
"""WITH source AS (SELECT text FROM docs WHERE id = :id)
SELECT d.text, vec_distance_cosine(d.embedding, vec_f32(:similar_to)) as distance
FROM docs d, source
WHERE d.id != :id
ORDER BY distance LIMIT 5"""",
bindings={
"id": 123,
"similar_to": {"_embedding_col": "text"} # References text from source CTE
}
)
```
Available Distance Functions:
- vec_distance_cosine(v1, v2) -> float: Cosine similarity (range 0-1, lower=more similar)
- vec_distance_L2(v1, v2) -> float: Euclidean distance (range 0-inf, lower=more similar)
- vec_distance_L1(v1, v2) -> float: Manhattan distance (range 0-inf, lower=more similar)
## Return Format:
- operation_was_successful: boolean
- error_message_if_operation_failed: string or null
- rows_modified_by_operation: integer or null for SELECT
- column_names_in_result_set: array or null for non-SELECT
- data_rows_from_result_set: array of row objects or null for non-SELECT
## Features:
- Automatic connection caching per database
- Row results as dictionaries with column name access
- Auto-commit for INSERT/UPDATE/DELETE
- Full SQLite feature set available
- Built-in vector similarity search
- Automatic Gemini embedding generation
## Important Limitations:
- Thread Safety: SQLite connections are thread-local
- Concurrent Access: Only one writer at a time
- Memory DB Scope: :memory: database persists for server lifetime
- File Location: Database files with simple names (no path separators) are created
in the same directory as run_ragtag_sse.py (typically python/ragtag/run_ragtag_sse.py
in the project root). Use full paths, @appdata/, or ~/ to store elsewhere.
- Embedding Generation: Requires GEMINI_API_KEY environment variable
- Vector Operations: Always use vec_f32() in SQL for vector parameters
## Common Error Cases:
- 'CHECK constraint failed': Missing vec_f32() in SQL for vector operations
- 'GEMINI_API_KEY environment variable not set': Configure API key
- 'Referenced column not found': Check binding names match SQL parameters
- 'Failed to generate embedding': Check API key and network connection
## SQLite Dot Commands:
The following dot commands are supported for convenience:
.tables - List all tables
.schema - Show schema for table(s)
.indexes - Show indexes for table
.fullschema - Complete schema dump
.dbinfo - Show database information
.status - Show current settings
.pragma - Show all PRAGMA settings
.foreign_keys - Show foreign key settings
Note: While dot commands are supported for convenience, standard SQL
queries are preferred as they provide more explicit and complete functionality.
## PRAGMA Support:
All PRAGMA statements are supported using standard SQL syntax:
PRAGMA foreign_keys = ON; -- Enable foreign keys
PRAGMA journal_mode = WAL; -- Set journal mode
PRAGMA synchronous = NORMAL; -- Configure sync mode
PRAGMA cache_size = -2000; -- Set cache size
PRAGMA page_size; -- Get page size
PRAGMA encoding; -- Get database encoding
## Examples
```json
# Basic SQL query
{
"input": {
"sql": "SELECT * FROM users WHERE age > :min_age",
"database": "myapp.db",
"bindings": {"min_age": 18},
"tool_unlock_token": "21639ee1"
}
}
# User-specific query using authenticated username
{
"input": {
"sql": "SELECT * FROM user_documents WHERE owner = :authenticated_user",
"database": "myapp.db",
"tool_unlock_token": "21639ee1"
}
}
# Insert with user tracking
{
"input": {
"sql": "INSERT INTO actions (user, action, timestamp) VALUES (:authenticated_user, :action, datetime('now'))",
"database": "audit.db",
"bindings": {"action": "document_created"},
"tool_unlock_token": "21639ee1"
}
}
# Vector similarity search
{
"input": {
"sql": "SELECT * FROM documents WHERE vec_distance_cosine(embedding, vec_f32(:vec)) < 0.5",
"database": "vectors.db",
"bindings": {"vec": {"_embedding_text": "Find similar documents"}},
"tool_unlock_token": "21639ee1"
}
}
```
github
Parameters Schema
{
"properties": {
"input": {
"type": "object",
"description": "All tool parameters are passed in this single dict. Use {\"input\":{\"operation\":\"readme\"}} to get full documentation, parameters, and an unlock token."
}
},
"required": [],
"type": "object"
}
use this tool for all github-related work
## Available Operations
## Usage-Safety Token System
This tool uses an hmac-based token system to ensure callers fully understand all details of
using this tool, on every call. The token is specific to this installation, user, and code version.
Your tool_unlock_token for this installation is: 82c6978f
You MUST include tool_unlock_token in the input dict for all operations except readme.
## Input Structure
All parameters are passed in a single 'input' dict:
1. For this documentation:
{
"input": {"operation": "readme"}
}
2. For executing operations:
{
"input": {
"operation": "operation_name",
"tool_unlock_token": "82c6978f",
... additional parameters specific to the operation ...
}
}
## Operation Schemas
### add_comment_to_pending_review
Add review comment to the requester's latest pending pull request review. A pending review needs to already exist to call this (check with the user if not sure).
Example usage:
{
"input": {
"operation": "add_comment_to_pending_review",
"tool_unlock_token": "82c6978f",
"body": "example_body" // REQUIRED // The text of the review comment,
"line": 123 // The line of the blob in the pull request diff that the comment applies to. For multi-line comments, the last line of the range,
"owner": "example_owner" // REQUIRED // Repository owner,
"path": "example_path" // REQUIRED // The relative path to the file that necessitates a comment,
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name,
"side": "example_side" // The side of the diff to comment on. LEFT indicates the previous state, RIGHT indicates the new state,
"startLine": 123 // For multi-line comments, the first line of the range that the comment applies to,
"startSide": "example_startSide" // For multi-line comments, the starting side of the diff that the comment applies to. LEFT indicates the previous state, RIGHT indicates the new state,
"subjectType": "example_subjectType" // REQUIRED // The level at which the comment is targeted
}
}
### add_issue_comment
Add a comment to a specific issue in a GitHub repository.
Example usage:
{
"input": {
"operation": "add_issue_comment",
"tool_unlock_token": "82c6978f",
"body": "example_body" // REQUIRED // Comment content,
"issue_number": 123 // REQUIRED // Issue number to comment on,
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### add_sub_issue
Add a sub-issue to a parent issue in a GitHub repository.
Example usage:
{
"input": {
"operation": "add_sub_issue",
"tool_unlock_token": "82c6978f",
"issue_number": 123 // REQUIRED // The number of the parent issue,
"owner": "example_owner" // REQUIRED // Repository owner,
"replace_parent": true // When true, replaces the sub-issue's current parent issue,
"repo": "example_repo" // REQUIRED // Repository name,
"sub_issue_id": 123 // REQUIRED // The ID of the sub-issue to add. ID is not the same as issue number
}
}
### assign_copilot_to_issue
Assign Copilot to a specific issue in a GitHub repository.
This tool can help with the following outcomes:
- a Pull Request created with source code changes to resolve the issue
More information can be found at:
- https://docs.github.com/en/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks/about-assigning-tasks-to-copilot
Example usage:
{
"input": {
"operation": "assign_copilot_to_issue",
"tool_unlock_token": "82c6978f",
"issueNumber": 123 // REQUIRED // Issue number,
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### cancel_workflow_run
Cancel a workflow run
Example usage:
{
"input": {
"operation": "cancel_workflow_run",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"run_id": 123 // REQUIRED // The unique identifier of the workflow run
}
}
### create_and_submit_pull_request_review
Create and submit a review for a pull request without review comments.
Example usage:
{
"input": {
"operation": "create_and_submit_pull_request_review",
"tool_unlock_token": "82c6978f",
"body": "example_body" // REQUIRED // Review comment text,
"commitID": "example_commitID" // SHA of commit to review,
"event": "example_event" // REQUIRED // Review action to perform,
"owner": "example_owner" // REQUIRED // Repository owner,
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### create_branch
Create a new branch in a GitHub repository
Example usage:
{
"input": {
"operation": "create_branch",
"tool_unlock_token": "82c6978f",
"branch": "example_branch" // REQUIRED // Name for new branch,
"from_branch": "example_from_branch" // Source branch (defaults to repo default),
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### create_issue
Create a new issue in a GitHub repository.
Example usage:
{
"input": {
"operation": "create_issue",
"tool_unlock_token": "82c6978f",
"assignees": ["item1", "item2"] // Usernames to assign to this issue,
"body": "example_body" // Issue body content,
"labels": ["item1", "item2"] // Labels to apply to this issue,
"milestone": 123 // Milestone number,
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"title": "example_title" // REQUIRED // Issue title
}
}
### create_or_update_file
Create or update a single file in a GitHub repository. If updating, you must provide the SHA of the file you want to update. Use this tool to create or update a file in a GitHub repository remotely; do not use it for local file operations.
Example usage:
{
"input": {
"operation": "create_or_update_file",
"tool_unlock_token": "82c6978f",
"branch": "example_branch" // REQUIRED // Branch to create/update the file in,
"content": "example_content" // REQUIRED // Content of the file,
"message": "example_message" // REQUIRED // Commit message,
"owner": "example_owner" // REQUIRED // Repository owner (username or organization),
"path": "example_path" // REQUIRED // Path where to create/update the file,
"repo": "example_repo" // REQUIRED // Repository name,
"sha": "example_sha" // Required if updating an existing file. The blob SHA of the file being replaced.
}
}
### create_pending_pull_request_review
Create a pending review for a pull request. Call this first before attempting to add comments to a pending review, and ultimately submitting it. A pending pull request review means a pull request review, it is pending because you create it first and submit it later, and the PR author will not see it until it is submitted.
Example usage:
{
"input": {
"operation": "create_pending_pull_request_review",
"tool_unlock_token": "82c6978f",
"commitID": "example_commitID" // SHA of commit to review,
"owner": "example_owner" // REQUIRED // Repository owner,
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### create_pull_request
Create a new pull request in a GitHub repository.
Example usage:
{
"input": {
"operation": "create_pull_request",
"tool_unlock_token": "82c6978f",
"base": "example_base" // REQUIRED // Branch to merge into,
"body": "example_body" // PR description,
"draft": true // Create as draft PR,
"head": "example_head" // REQUIRED // Branch containing changes,
"maintainer_can_modify": true // Allow maintainer edits,
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"title": "example_title" // REQUIRED // PR title
}
}
### create_repository
Create a new GitHub repository in your account
Example usage:
{
"input": {
"operation": "create_repository",
"tool_unlock_token": "82c6978f",
"autoInit": true // Initialize with README,
"description": "example_description" // Repository description,
"name": "example_name" // REQUIRED // Repository name,
"private": true // Whether repo should be private
}
}
### delete_file
Delete a file from a GitHub repository
Example usage:
{
"input": {
"operation": "delete_file",
"tool_unlock_token": "82c6978f",
"branch": "example_branch" // REQUIRED // Branch to delete the file from,
"message": "example_message" // REQUIRED // Commit message,
"owner": "example_owner" // REQUIRED // Repository owner (username or organization),
"path": "example_path" // REQUIRED // Path to the file to delete,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### delete_pending_pull_request_review
Delete the requester's latest pending pull request review. Use this after the user decides not to submit a pending review, if you don't know if they already created one then check first.
Example usage:
{
"input": {
"operation": "delete_pending_pull_request_review",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### delete_workflow_run_logs
Delete logs for a workflow run
Example usage:
{
"input": {
"operation": "delete_workflow_run_logs",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"run_id": 123 // REQUIRED // The unique identifier of the workflow run
}
}
### dismiss_notification
Dismiss a notification by marking it as read or done
Example usage:
{
"input": {
"operation": "dismiss_notification",
"tool_unlock_token": "82c6978f",
"state": "example_state" // The new state of the notification (read/done),
"threadID": "example_threadID" // REQUIRED // The ID of the notification thread
}
}
### download_workflow_run_artifact
Get download URL for a workflow run artifact
Example usage:
{
"input": {
"operation": "download_workflow_run_artifact",
"tool_unlock_token": "82c6978f",
"artifact_id": 123 // REQUIRED // The unique identifier of the artifact,
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### fork_repository
Fork a GitHub repository to your account or specified organization
Example usage:
{
"input": {
"operation": "fork_repository",
"tool_unlock_token": "82c6978f",
"organization": "example_organization" // Organization to fork to,
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### get_code_scanning_alert
Get details of a specific code scanning alert in a GitHub repository.
Example usage:
{
"input": {
"operation": "get_code_scanning_alert",
"tool_unlock_token": "82c6978f",
"alertNumber": 123 // REQUIRED // The number of the alert.,
"owner": "example_owner" // REQUIRED // The owner of the repository.,
"repo": "example_repo" // REQUIRED // The name of the repository.
}
}
### get_commit
Get details for a commit from a GitHub repository
Example usage:
{
"input": {
"operation": "get_commit",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // REQUIRED // Repository name,
"sha": "example_sha" // REQUIRED // Commit SHA, branch name, or tag name
}
}
### get_dependabot_alert
Get details of a specific dependabot alert in a GitHub repository.
Example usage:
{
"input": {
"operation": "get_dependabot_alert",
"tool_unlock_token": "82c6978f",
"alertNumber": 123 // REQUIRED // The number of the alert.,
"owner": "example_owner" // REQUIRED // The owner of the repository.,
"repo": "example_repo" // REQUIRED // The name of the repository.
}
}
### get_discussion
Get a specific discussion by ID
Example usage:
{
"input": {
"operation": "get_discussion",
"tool_unlock_token": "82c6978f",
"discussionNumber": 123 // REQUIRED // Discussion Number,
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### get_discussion_comments
Get comments from a discussion
Example usage:
{
"input": {
"operation": "get_discussion_comments",
"tool_unlock_token": "82c6978f",
"after": "example_after" // Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs.,
"discussionNumber": 123 // REQUIRED // Discussion Number,
"owner": "example_owner" // REQUIRED // Repository owner,
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // REQUIRED // Repository name
}
}
### get_file_contents
Get the contents of a file or directory from a GitHub repository
Example usage:
{
"input": {
"operation": "get_file_contents",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner (username or organization),
"path": "example_path" // Path to file/directory (directories must end with a slash '/'),
"ref": "example_ref" // Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head`,
"repo": "example_repo" // REQUIRED // Repository name,
"sha": "example_sha" // Accepts optional commit SHA. If specified, it will be used instead of ref
}
}
### get_issue
Get details of a specific issue in a GitHub repository.
Example usage:
{
"input": {
"operation": "get_issue",
"tool_unlock_token": "82c6978f",
"issue_number": 123 // REQUIRED // The number of the issue,
"owner": "example_owner" // REQUIRED // The owner of the repository,
"repo": "example_repo" // REQUIRED // The name of the repository
}
}
### get_issue_comments
Get comments for a specific issue in a GitHub repository.
Example usage:
{
"input": {
"operation": "get_issue_comments",
"tool_unlock_token": "82c6978f",
"issue_number": 123 // REQUIRED // Issue number,
"owner": "example_owner" // REQUIRED // Repository owner,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // REQUIRED // Repository name
}
}
### get_job_logs
Download logs for a specific workflow job or efficiently get all failed job logs for a workflow run
Example usage:
{
"input": {
"operation": "get_job_logs",
"tool_unlock_token": "82c6978f",
"failed_only": true // When true, gets logs for all failed jobs in run_id,
"job_id": 123 // The unique identifier of the workflow job (required for single job logs),
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"return_content": true // Returns actual log content instead of URLs,
"run_id": 123 // Workflow run ID (required when using failed_only),
"tail_lines": 123 // Number of lines to return from the end of the log
}
}
### get_me
Get details of the authenticated GitHub user. Use this when a request is about the user's own profile for GitHub. Or when information is missing to build other tool calls.
Example usage:
{
"input": {
"operation": "get_me",
"tool_unlock_token": "82c6978f",
// No additional parameters
}
}
### get_notification_details
Get detailed information for a specific GitHub notification, always call this tool when the user asks for details about a specific notification, if you don't know the ID list notifications first.
Example usage:
{
"input": {
"operation": "get_notification_details",
"tool_unlock_token": "82c6978f",
"notificationID": "example_notificationID" // REQUIRED // The ID of the notification
}
}
### get_pull_request
Get details of a specific pull request in a GitHub repository.
Example usage:
{
"input": {
"operation": "get_pull_request",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### get_pull_request_comments
Get comments for a specific pull request.
Example usage:
{
"input": {
"operation": "get_pull_request_comments",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### get_pull_request_diff
Get the diff of a pull request.
Example usage:
{
"input": {
"operation": "get_pull_request_diff",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### get_pull_request_files
Get the files changed in a specific pull request.
Example usage:
{
"input": {
"operation": "get_pull_request_files",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### get_pull_request_reviews
Get reviews for a specific pull request.
Example usage:
{
"input": {
"operation": "get_pull_request_reviews",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### get_pull_request_status
Get the status of a specific pull request.
Example usage:
{
"input": {
"operation": "get_pull_request_status",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### get_secret_scanning_alert
Get details of a specific secret scanning alert in a GitHub repository.
Example usage:
{
"input": {
"operation": "get_secret_scanning_alert",
"tool_unlock_token": "82c6978f",
"alertNumber": 123 // REQUIRED // The number of the alert.,
"owner": "example_owner" // REQUIRED // The owner of the repository.,
"repo": "example_repo" // REQUIRED // The name of the repository.
}
}
### get_tag
Get details about a specific git tag in a GitHub repository
Example usage:
{
"input": {
"operation": "get_tag",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"tag": "example_tag" // REQUIRED // Tag name
}
}
### get_workflow_run
Get details of a specific workflow run
Example usage:
{
"input": {
"operation": "get_workflow_run",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"run_id": 123 // REQUIRED // The unique identifier of the workflow run
}
}
### get_workflow_run_logs
Download logs for a specific workflow run (EXPENSIVE: downloads ALL logs as ZIP. Consider using get_job_logs with failed_only=true for debugging failed jobs)
Example usage:
{
"input": {
"operation": "get_workflow_run_logs",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"run_id": 123 // REQUIRED // The unique identifier of the workflow run
}
}
### get_workflow_run_usage
Get usage metrics for a workflow run
Example usage:
{
"input": {
"operation": "get_workflow_run_usage",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"run_id": 123 // REQUIRED // The unique identifier of the workflow run
}
}
### list_branches
List branches in a GitHub repository
Example usage:
{
"input": {
"operation": "list_branches",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // REQUIRED // Repository name
}
}
### list_code_scanning_alerts
List code scanning alerts in a GitHub repository.
Example usage:
{
"input": {
"operation": "list_code_scanning_alerts",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // The owner of the repository.,
"ref": "example_ref" // The Git reference for the results you want to list.,
"repo": "example_repo" // REQUIRED // The name of the repository.,
"severity": "example_severity" // Filter code scanning alerts by severity,
"state": "example_state" // Filter code scanning alerts by state. Defaults to open,
"tool_name": "example_tool_name" // The name of the tool used for code scanning.
}
}
### list_commits
Get list of commits of a branch in a GitHub repository. Returns at least 30 results per page by default, but can return more if specified using the perPage parameter (up to 100).
Example usage:
{
"input": {
"operation": "list_commits",
"tool_unlock_token": "82c6978f",
"author": "example_author" // Author username or email address to filter commits by,
"owner": "example_owner" // REQUIRED // Repository owner,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // REQUIRED // Repository name,
"sha": "example_sha" // Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch of the repository. If a commit SHA is provided, will list commits up to that SHA.
}
}
### list_dependabot_alerts
List dependabot alerts in a GitHub repository.
Example usage:
{
"input": {
"operation": "list_dependabot_alerts",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // The owner of the repository.,
"repo": "example_repo" // REQUIRED // The name of the repository.,
"severity": "example_severity" // Filter dependabot alerts by severity,
"state": "example_state" // Filter dependabot alerts by state. Defaults to open
}
}
### list_discussion_categories
List discussion categories with their id and name, for a repository
Example usage:
{
"input": {
"operation": "list_discussion_categories",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### list_discussions
List discussions for a repository
Example usage:
{
"input": {
"operation": "list_discussions",
"tool_unlock_token": "82c6978f",
"after": "example_after" // Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs.,
"category": "example_category" // Optional filter by discussion category ID. If provided, only discussions with this category are listed.,
"owner": "example_owner" // REQUIRED // Repository owner,
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // REQUIRED // Repository name
}
}
### list_issues
List issues in a GitHub repository.
Example usage:
{
"input": {
"operation": "list_issues",
"tool_unlock_token": "82c6978f",
"direction": "example_direction" // Sort direction,
"labels": ["item1", "item2"] // Filter by labels,
"owner": "example_owner" // REQUIRED // Repository owner,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // REQUIRED // Repository name,
"since": "example_since" // Filter by date (ISO 8601 timestamp),
"sort": "example_sort" // Sort order,
"state": "example_state" // Filter by state
}
}
### list_notifications
Lists all GitHub notifications for the authenticated user, including unread notifications, mentions, review requests, assignments, and updates on issues or pull requests. Use this tool whenever the user asks what to work on next, requests a summary of their GitHub activity, wants to see pending reviews, or needs to check for new updates or tasks. This tool is the primary way to discover actionable items, reminders, and outstanding work on GitHub. Always call this tool when asked what to work on next, what is pending, or what needs attention in GitHub.
Example usage:
{
"input": {
"operation": "list_notifications",
"tool_unlock_token": "82c6978f",
"before": "example_before" // Only show notifications updated before the given time (ISO 8601 format),
"filter": "example_filter" // Filter notifications to, use default unless specified. Read notifications are ones that have already been acknowledged by the user. Participating notifications are those that the user is directly involved in, such as issues or pull requests they have commented on or created.,
"owner": "example_owner" // Optional repository owner. If provided with repo, only notifications for this repository are listed.,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // Optional repository name. If provided with owner, only notifications for this repository are listed.,
"since": "example_since" // Only show notifications updated after the given time (ISO 8601 format)
}
}
### list_pull_requests
List pull requests in a GitHub repository. If the user specifies an author, then DO NOT use this tool and use the search_pull_requests tool instead.
Example usage:
{
"input": {
"operation": "list_pull_requests",
"tool_unlock_token": "82c6978f",
"base": "example_base" // Filter by base branch,
"direction": "example_direction" // Sort direction,
"head": "example_head" // Filter by head user/org and branch,
"owner": "example_owner" // REQUIRED // Repository owner,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // REQUIRED // Repository name,
"sort": "example_sort" // Sort by,
"state": "example_state" // Filter by state
}
}
### list_secret_scanning_alerts
List secret scanning alerts in a GitHub repository.
Example usage:
{
"input": {
"operation": "list_secret_scanning_alerts",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // The owner of the repository.,
"repo": "example_repo" // REQUIRED // The name of the repository.,
"resolution": "example_resolution" // Filter by resolution,
"secret_type": "example_secret_type" // A comma-separated list of secret types to return. All default secret patterns are returned. To return generic patterns, pass the token name(s) in the parameter.,
"state": "example_state" // Filter by state
}
}
### list_sub_issues
List sub-issues for a specific issue in a GitHub repository.
Example usage:
{
"input": {
"operation": "list_sub_issues",
"tool_unlock_token": "82c6978f",
"issue_number": 123 // REQUIRED // Issue number,
"owner": "example_owner" // REQUIRED // Repository owner,
"page": 123 // Page number for pagination (default: 1),
"per_page": 123 // Number of results per page (max 100, default: 30),
"repo": "example_repo" // REQUIRED // Repository name
}
}
### list_tags
List git tags in a GitHub repository
Example usage:
{
"input": {
"operation": "list_tags",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // REQUIRED // Repository name
}
}
### list_workflow_jobs
List jobs for a specific workflow run
Example usage:
{
"input": {
"operation": "list_workflow_jobs",
"tool_unlock_token": "82c6978f",
"filter": "example_filter" // Filters jobs by their completed_at timestamp,
"owner": "example_owner" // REQUIRED // Repository owner,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // REQUIRED // Repository name,
"run_id": 123 // REQUIRED // The unique identifier of the workflow run
}
}
### list_workflow_run_artifacts
List artifacts for a workflow run
Example usage:
{
"input": {
"operation": "list_workflow_run_artifacts",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // REQUIRED // Repository name,
"run_id": 123 // REQUIRED // The unique identifier of the workflow run
}
}
### list_workflow_runs
List workflow runs for a specific workflow
Example usage:
{
"input": {
"operation": "list_workflow_runs",
"tool_unlock_token": "82c6978f",
"actor": "example_actor" // Returns someone's workflow runs. Use the login for the user who created the workflow run.,
"branch": "example_branch" // Returns workflow runs associated with a branch. Use the name of the branch.,
"event": "example_event" // Returns workflow runs for a specific event type,
"owner": "example_owner" // REQUIRED // Repository owner,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // REQUIRED // Repository name,
"status": "example_status" // Returns workflow runs with the check run status,
"workflow_id": "example_workflow_id" // REQUIRED // The workflow ID or workflow file name
}
}
### list_workflows
List workflows in a repository
Example usage:
{
"input": {
"operation": "list_workflows",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"repo": "example_repo" // REQUIRED // Repository name
}
}
### manage_notification_subscription
Manage a notification subscription: ignore, watch, or delete a notification thread subscription.
Example usage:
{
"input": {
"operation": "manage_notification_subscription",
"tool_unlock_token": "82c6978f",
"action": "example_action" // REQUIRED // Action to perform: ignore, watch, or delete the notification subscription.,
"notificationID": "example_notificationID" // REQUIRED // The ID of the notification thread.
}
}
### manage_repository_notification_subscription
Manage a repository notification subscription: ignore, watch, or delete repository notifications subscription for the provided repository.
Example usage:
{
"input": {
"operation": "manage_repository_notification_subscription",
"tool_unlock_token": "82c6978f",
"action": "example_action" // REQUIRED // Action to perform: ignore, watch, or delete the repository notification subscription.,
"owner": "example_owner" // REQUIRED // The account owner of the repository.,
"repo": "example_repo" // REQUIRED // The name of the repository.
}
}
### mark_all_notifications_read
Mark all notifications as read
Example usage:
{
"input": {
"operation": "mark_all_notifications_read",
"tool_unlock_token": "82c6978f",
"lastReadAt": "example_lastReadAt" // Describes the last point that notifications were checked (optional). Default: Now,
"owner": "example_owner" // Optional repository owner. If provided with repo, only notifications for this repository are marked as read.,
"repo": "example_repo" // Optional repository name. If provided with owner, only notifications for this repository are marked as read.
}
}
### merge_pull_request
Merge a pull request in a GitHub repository.
Example usage:
{
"input": {
"operation": "merge_pull_request",
"tool_unlock_token": "82c6978f",
"commit_message": "example_commit_message" // Extra detail for merge commit,
"commit_title": "example_commit_title" // Title for merge commit,
"merge_method": "example_merge_method" // Merge method,
"owner": "example_owner" // REQUIRED // Repository owner,
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### push_files
Push multiple files to a GitHub repository in a single commit
Example usage:
{
"input": {
"operation": "push_files",
"tool_unlock_token": "82c6978f",
"branch": "example_branch" // REQUIRED // Branch to push to,
"files": ["item1", "item2"] // REQUIRED // Array of file objects to push, each object with path (string) and content (string),
"message": "example_message" // REQUIRED // Commit message,
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### remove_sub_issue
Remove a sub-issue from a parent issue in a GitHub repository.
Example usage:
{
"input": {
"operation": "remove_sub_issue",
"tool_unlock_token": "82c6978f",
"issue_number": 123 // REQUIRED // The number of the parent issue,
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"sub_issue_id": 123 // REQUIRED // The ID of the sub-issue to remove. ID is not the same as issue number
}
}
### reprioritize_sub_issue
Reprioritize a sub-issue to a different position in the parent issue's sub-issue list.
Example usage:
{
"input": {
"operation": "reprioritize_sub_issue",
"tool_unlock_token": "82c6978f",
"after_id": 123 // The ID of the sub-issue to be prioritized after (either after_id OR before_id should be specified),
"before_id": 123 // The ID of the sub-issue to be prioritized before (either after_id OR before_id should be specified),
"issue_number": 123 // REQUIRED // The number of the parent issue,
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"sub_issue_id": 123 // REQUIRED // The ID of the sub-issue to reprioritize. ID is not the same as issue number
}
}
### request_copilot_review
Request a GitHub Copilot code review for a pull request. Use this for automated feedback on pull requests, usually before requesting a human reviewer.
Example usage:
{
"input": {
"operation": "request_copilot_review",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### rerun_failed_jobs
Re-run only the failed jobs in a workflow run
Example usage:
{
"input": {
"operation": "rerun_failed_jobs",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"run_id": 123 // REQUIRED // The unique identifier of the workflow run
}
}
### rerun_workflow_run
Re-run an entire workflow run
Example usage:
{
"input": {
"operation": "rerun_workflow_run",
"tool_unlock_token": "82c6978f",
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"run_id": 123 // REQUIRED // The unique identifier of the workflow run
}
}
### run_workflow
Run an Actions workflow by workflow ID or filename
Example usage:
{
"input": {
"operation": "run_workflow",
"tool_unlock_token": "82c6978f",
"inputs": {} // Inputs the workflow accepts,
"owner": "example_owner" // REQUIRED // Repository owner,
"ref": "example_ref" // REQUIRED // The git reference for the workflow. The reference can be a branch or tag name.,
"repo": "example_repo" // REQUIRED // Repository name,
"workflow_id": "example_workflow_id" // REQUIRED // The workflow ID (numeric) or workflow file name (e.g., main.yml, ci.yaml)
}
}
### search_code
Search for code across GitHub repositories
Example usage:
{
"input": {
"operation": "search_code",
"tool_unlock_token": "82c6978f",
"order": "example_order" // Sort order,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"q": "example_q" // REQUIRED // Search query using GitHub code search syntax,
"sort": "example_sort" // Sort field ('indexed' only)
}
}
### search_issues
Search for issues in GitHub repositories using issues search syntax already scoped to is:issue
Example usage:
{
"input": {
"operation": "search_issues",
"tool_unlock_token": "82c6978f",
"order": "example_order" // Sort order,
"owner": "example_owner" // Optional repository owner. If provided with repo, only notifications for this repository are listed.,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"query": "example_query" // REQUIRED // Search query using GitHub issues search syntax,
"repo": "example_repo" // Optional repository name. If provided with owner, only notifications for this repository are listed.,
"sort": "example_sort" // Sort field by number of matches of categories, defaults to best match
}
}
### search_orgs
Search for GitHub organizations exclusively
Example usage:
{
"input": {
"operation": "search_orgs",
"tool_unlock_token": "82c6978f",
"order": "example_order" // Sort order,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"query": "example_query" // REQUIRED // Search query using GitHub organizations search syntax scoped to type:org,
"sort": "example_sort" // Sort field by category
}
}
### search_pull_requests
Search for pull requests in GitHub repositories using issues search syntax already scoped to is:pr
Example usage:
{
"input": {
"operation": "search_pull_requests",
"tool_unlock_token": "82c6978f",
"order": "example_order" // Sort order,
"owner": "example_owner" // Optional repository owner. If provided with repo, only notifications for this repository are listed.,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"query": "example_query" // REQUIRED // Search query using GitHub pull request search syntax,
"repo": "example_repo" // Optional repository name. If provided with owner, only notifications for this repository are listed.,
"sort": "example_sort" // Sort field by number of matches of categories, defaults to best match
}
}
### search_repositories
Search for GitHub repositories
Example usage:
{
"input": {
"operation": "search_repositories",
"tool_unlock_token": "82c6978f",
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"query": "example_query" // REQUIRED // Search query
}
}
### search_users
Search for GitHub users exclusively
Example usage:
{
"input": {
"operation": "search_users",
"tool_unlock_token": "82c6978f",
"order": "example_order" // Sort order,
"page": 123 // Page number for pagination (min 1),
"perPage": 123 // Results per page for pagination (min 1, max 100),
"query": "example_query" // REQUIRED // Search query using GitHub users search syntax scoped to type:user,
"sort": "example_sort" // Sort field by category
}
}
### submit_pending_pull_request_review
Submit the requester's latest pending pull request review, normally this is a final step after creating a pending review, adding comments first, unless you know that the user already did the first two steps, you should check before calling this.
Example usage:
{
"input": {
"operation": "submit_pending_pull_request_review",
"tool_unlock_token": "82c6978f",
"body": "example_body" // The text of the review comment,
"event": "example_event" // REQUIRED // The event to perform,
"owner": "example_owner" // REQUIRED // Repository owner,
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name
}
}
### update_issue
Update an existing issue in a GitHub repository.
Example usage:
{
"input": {
"operation": "update_issue",
"tool_unlock_token": "82c6978f",
"assignees": ["item1", "item2"] // New assignees,
"body": "example_body" // New description,
"issue_number": 123 // REQUIRED // Issue number to update,
"labels": ["item1", "item2"] // New labels,
"milestone": 123 // New milestone number,
"owner": "example_owner" // REQUIRED // Repository owner,
"repo": "example_repo" // REQUIRED // Repository name,
"state": "example_state" // New state,
"title": "example_title" // New title
}
}
### update_pull_request
Update an existing pull request in a GitHub repository.
Example usage:
{
"input": {
"operation": "update_pull_request",
"tool_unlock_token": "82c6978f",
"base": "example_base" // New base branch name,
"body": "example_body" // New description,
"maintainer_can_modify": true // Allow maintainer edits,
"owner": "example_owner" // REQUIRED // Repository owner,
"pullNumber": 123 // REQUIRED // Pull request number to update,
"repo": "example_repo" // REQUIRED // Repository name,
"state": "example_state" // New state,
"title": "example_title" // New title
}
}
### update_pull_request_branch
Update the branch of a pull request with the latest changes from the base branch.
Example usage:
{
"input": {
"operation": "update_pull_request_branch",
"tool_unlock_token": "82c6978f",
"expectedHeadSha": "example_expectedHeadSha" // The expected SHA of the pull request's HEAD ref,
"owner": "example_owner" // REQUIRED // Repository owner,
"pullNumber": 123 // REQUIRED // Pull request number,
"repo": "example_repo" // REQUIRED // Repository name
}
}
desktop_commander
Parameters Schema
{
"properties": {
"input": {
"type": "object",
"description": "All tool parameters are passed in this single dict. Use {\"input\":{\"operation\":\"readme\"}} to get full documentation, parameters, and an unlock token."
}
},
"required": [],
"type": "object"
}
use this tool when you need to perform file-based operations on the users PC
## Available Operations
## Usage-Safety Token System
This tool uses an hmac-based token system to ensure callers fully understand all details of
using this tool, on every call. The token is specific to this installation, user, and code version.
Your tool_unlock_token for this installation is: 82c6978f
You MUST include tool_unlock_token in the input dict for all operations except readme.
## Input Structure
All parameters are passed in a single 'input' dict:
1. For this documentation:
{
"input": {"operation": "readme"}
}
2. For executing operations:
{
"input": {
"operation": "operation_name",
"tool_unlock_token": "82c6978f",
... additional parameters specific to the operation ...
}
}
## Operation Schemas
### get_config
Get the complete server configuration as JSON. Config includes fields for:
- blockedCommands (array of blocked shell commands)
- defaultShell (shell to use for commands)
- allowedDirectories (paths the server can access)
- fileReadLineLimit (max lines for read_file, default 1000)
- fileWriteLineLimit (max lines per write_file call, default 50)
- telemetryEnabled (boolean for telemetry opt-in/out)
- version (version of the DesktopCommander)
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "get_config",
"tool_unlock_token": "82c6978f",
// No additional parameters
}
}
### set_config_value
Set a specific configuration value by key.
WARNING: Should be used in a separate chat from file operations and
command execution to prevent security issues.
Config keys include:
- blockedCommands (array)
- defaultShell (string)
- allowedDirectories (array of paths)
- fileReadLineLimit (number, max lines for read_file)
- fileWriteLineLimit (number, max lines per write_file call)
- telemetryEnabled (boolean)
IMPORTANT: Setting allowedDirectories to an empty array ([]) allows full access
to the entire file system, regardless of the operating system.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "set_config_value",
"tool_unlock_token": "82c6978f",
"key": "example_key" // REQUIRED // ,
"value": "example_value" //
}
}
### read_file
Read the contents of a file from the file system or a URL with optional offset and length parameters.
Prefer this over 'execute_command' with cat/type for viewing files.
Supports partial file reading with:
- 'offset' (start line, default: 0)
- 'length' (max lines to read, default: configurable via 'fileReadLineLimit' setting, initially 1000)
When reading from the file system, only works within allowed directories.
Can fetch content from URLs when isUrl parameter is set to true
(URLs are always read in full regardless of offset/length).
Handles text files normally and image files are returned as viewable images.
Recognized image types: PNG, JPEG, GIF, WebP.
IMPORTANT: Always use absolute paths (starting with '/' or drive letter like 'C:\') for reliability. Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "read_file",
"tool_unlock_token": "82c6978f",
"path": "example_path" // REQUIRED // ,
"isUrl": true // ,
"offset": 123 // ,
"length": 123 //
}
}
### read_multiple_files
Read the contents of multiple files simultaneously.
Each file's content is returned with its path as a reference.
Handles text files normally and renders images as viewable content.
Recognized image types: PNG, JPEG, GIF, WebP.
Failed reads for individual files won't stop the entire operation.
Only works within allowed directories.
IMPORTANT: Always use absolute paths (starting with '/' or drive letter like 'C:\') for reliability. Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "read_multiple_files",
"tool_unlock_token": "82c6978f",
"paths": ["item1", "item2"] // REQUIRED //
}
}
### write_file
Write or append to file contents with a configurable line limit per call (default: 50 lines).
THIS IS A STRICT REQUIREMENT. ANY file with more than the configured limit MUST BE written in chunks or IT WILL FAIL.
⚠️ IMPORTANT: PREVENTATIVE CHUNKING REQUIRED in these scenarios:
1. When content exceeds 2,000 words or 30 lines
2. When writing MULTIPLE files one after another (each next file is more likely to be truncated)
3. When the file is the LAST ONE in a series of operations in the same message
ALWAYS split files writes in to multiple smaller writes PREEMPTIVELY without asking the user in these scenarios.
REQUIRED PROCESS FOR LARGE NEW FILE WRITES OR REWRITES:
1. FIRST → write_file(filePath, firstChunk, {mode: 'rewrite'})
2. THEN → write_file(filePath, secondChunk, {mode: 'append'})
3. THEN → write_file(filePath, thirdChunk, {mode: 'append'})
... and so on for each chunk
HANDLING TRUNCATION ("Continue" prompts):
If user asked to "Continue" after unfinished file write:
1. First, read the file to find out what content was successfully written
2. Identify exactly where the content was truncated
3. Continue writing ONLY the remaining content using {mode: 'append'}
4. Split the remaining content into smaller chunks (15-20 lines per chunk)
Files over the line limit (configurable via 'fileWriteLineLimit' setting) WILL BE REJECTED if not broken into chunks as described above.
Only works within allowed directories.
IMPORTANT: Always use absolute paths (starting with '/' or drive letter like 'C:\') for reliability. Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "write_file",
"tool_unlock_token": "82c6978f",
"path": "example_path" // REQUIRED // ,
"content": "example_content" // REQUIRED // ,
"mode": "example_mode" //
}
}
### create_directory
Create a new directory or ensure a directory exists.
Can create multiple nested directories in one operation.
Only works within allowed directories.
IMPORTANT: Always use absolute paths (starting with '/' or drive letter like 'C:\') for reliability. Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "create_directory",
"tool_unlock_token": "82c6978f",
"path": "example_path" // REQUIRED //
}
}
### list_directory
Get a detailed listing of all files and directories in a specified path.
Use this instead of 'execute_command' with ls/dir commands.
Results distinguish between files and directories with [FILE] and [DIR] prefixes.
Only works within allowed directories.
IMPORTANT: Always use absolute paths (starting with '/' or drive letter like 'C:\') for reliability. Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "list_directory",
"tool_unlock_token": "82c6978f",
"path": "example_path" // REQUIRED //
}
}
### move_file
Move or rename files and directories.
Can move files between directories and rename them in a single operation.
Both source and destination must be within allowed directories.
IMPORTANT: Always use absolute paths (starting with '/' or drive letter like 'C:\') for reliability. Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "move_file",
"tool_unlock_token": "82c6978f",
"source": "example_source" // REQUIRED // ,
"destination": "example_destination" // REQUIRED //
}
}
### search_files
Finds files by name using a case-insensitive substring matching.
Use this instead of 'execute_command' with find/dir/ls for locating files.
Searches through all subdirectories from the starting path.
Has a default timeout of 30 seconds which can be customized using the timeoutMs parameter.
Only searches within allowed directories.
IMPORTANT: Always use absolute paths (starting with '/' or drive letter like 'C:\') for reliability. Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "search_files",
"tool_unlock_token": "82c6978f",
"path": "example_path" // REQUIRED // ,
"pattern": "example_pattern" // REQUIRED // ,
"timeoutMs": 123 //
}
}
### search_code
Search for text/code patterns within file contents using ripgrep.
Use this instead of 'execute_command' with grep/find for searching code content.
Fast and powerful search similar to VS Code search functionality.
Supports regular expressions, file pattern filtering, and context lines.
Has a default timeout of 30 seconds which can be customized.
Only searches within allowed directories.
IMPORTANT: Always use absolute paths (starting with '/' or drive letter like 'C:\') for reliability. Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "search_code",
"tool_unlock_token": "82c6978f",
"path": "example_path" // REQUIRED // ,
"pattern": "example_pattern" // REQUIRED // ,
"filePattern": "example_filePattern" // ,
"ignoreCase": true // ,
"maxResults": 123 // ,
"includeHidden": true // ,
"contextLines": 123 // ,
"timeoutMs": 123 //
}
}
### get_file_info
Retrieve detailed metadata about a file or directory including:
- size
- creation time
- last modified time
- permissions
- type
- lineCount (for text files)
- lastLine (zero-indexed number of last line, for text files)
- appendPosition (line number for appending, for text files)
Only works within allowed directories.
IMPORTANT: Always use absolute paths (starting with '/' or drive letter like 'C:\') for reliability. Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "get_file_info",
"tool_unlock_token": "82c6978f",
"path": "example_path" // REQUIRED //
}
}
### edit_block
Apply surgical text replacements to files.
BEST PRACTICE: Make multiple small, focused edits rather than one large edit.
Each edit_block call should change only what needs to be changed - include just enough
context to uniquely identify the text being modified.
Takes:
- file_path: Path to the file to edit
- old_string: Text to replace
- new_string: Replacement text
- expected_replacements: Optional parameter for number of replacements
By default, replaces only ONE occurrence of the search text.
To replace multiple occurrences, provide the expected_replacements parameter with
the exact number of matches expected.
UNIQUENESS REQUIREMENT: When expected_replacements=1 (default), include the minimal
amount of context necessary (typically 1-3 lines) before and after the change point,
with exact whitespace and indentation.
When editing multiple sections, make separate edit_block calls for each distinct change
rather than one large replacement.
When a close but non-exact match is found, a character-level diff is shown in the format:
common_prefix{-removed-}{+added+}common_suffix to help you identify what's different.
Similar to write_file, there is a configurable line limit (fileWriteLineLimit) that warns
if the edited file exceeds this limit. If this happens, consider breaking your edits into
smaller, more focused changes.
IMPORTANT: Always use absolute paths (starting with '/' or drive letter like 'C:\') for reliability. Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "edit_block",
"tool_unlock_token": "82c6978f",
"file_path": "example_file_path" // REQUIRED // ,
"old_string": "example_old_string" // REQUIRED // ,
"new_string": "example_new_string" // REQUIRED // ,
"expected_replacements": 123 //
}
}
### execute_command
Execute a terminal command with timeout.
Command will continue running in background if it doesn't complete within timeout.
NOTE: For file operations, prefer specialized tools like read_file, search_code,
list_directory instead of cat, grep, or ls commands.
IMPORTANT: Always use absolute paths (starting with '/' or drive letter like 'C:\') for reliability. Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "execute_command",
"tool_unlock_token": "82c6978f",
"command": "example_command" // REQUIRED // ,
"timeout_ms": 123 // REQUIRED // ,
"shell": "example_shell" //
}
}
### read_output
Read new output from a running terminal session.
Set timeout_ms for long running commands.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "read_output",
"tool_unlock_token": "82c6978f",
"pid": 123 // REQUIRED // ,
"timeout_ms": 123 //
}
}
### force_terminate
Force terminate a running terminal session.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "force_terminate",
"tool_unlock_token": "82c6978f",
"pid": 123 // REQUIRED //
}
}
### list_sessions
List all active terminal sessions.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "list_sessions",
"tool_unlock_token": "82c6978f",
// No additional parameters
}
}
### list_processes
List all running processes.
Returns process information including PID, command name, CPU usage, and memory usage.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "list_processes",
"tool_unlock_token": "82c6978f",
// No additional parameters
}
}
### kill_process
Terminate a running process by PID.
Use with caution as this will forcefully terminate the specified process.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Example usage:
{
"input": {
"operation": "kill_process",
"tool_unlock_token": "82c6978f",
"pid": 123 // REQUIRED //
}
}
openrouter
Parameters Schema
{
"properties": {
"input": {
"type": "object",
"description": "All tool parameters are passed in this single dict. Use {\"input\":{\"operation\":\"readme\"}} to get full documentation, parameters, and an unlock token."
}
},
"required": [],
"type": "object"
}
OpenRouter API tool providing access to multiple different AI models from multiple providers.
- Use this tool when asked for or about openrouter, or when you need help from an AI with different abilities to your own.
OpenRouter API integration providing access to multiple AI models.
Key Features:
1. Model Discovery & Search:
- Semantic search to find best models for specific tasks
- Vector similarity comparison of model capabilities
- Auto-refreshing model database (24h cache)
- Rich filtering options
2. Model Information:
- Context lengths and capabilities
- Pricing details
- Architecture specifications
- Provider-specific limits
3. Chat Completions:
- Support for multiple models
- Streaming responses
- Tool usage capabilities
- Source content processing (URL/file)
## Usage-Safety Token System
This tool uses an hmac-based token system to ensure callers fully understand all details of
using this tool, on every call. The token is specific to this installation, user, and code version.
Your tool_unlock_token for this installation is: 50f176de
You MUST include tool_unlock_token in the input dict for all operations except readme.
## Input Structure
All parameters are passed in a single 'input' dict:
1. For this documentation:
{
"input": {"operation": "readme"}
}
2. For all other operations:
{
"input": {
"operation": "operation_name",
"tool_unlock_token": "50f176de",
...other parameters...
}
}
Primary Operations:
1. search_models: Vector similarity search for finding task-specific models
Required parameters:
- operation: "search_models"
- tool_unlock_token: (see above)
Optional parameters:
- bindings: {"query_vec": {"_embedding_text": "your search text"}} (required only for semantic search)
- sql: Custom SQL query (if omitted, returns all columns)
- max_results: Maximum results to return (default 32)
Example - Semantic Search:
{
"input": {
"operation": "search_models",
"tool_unlock_token": "50f176de",
"bindings": {
"query_vec": {"_embedding_text": "code analysis and reasoning"}
}
}
}
Example - Non-Semantic Search (Top 5 by Context Length):
{
"input": {
"operation": "search_models",
"tool_unlock_token": "50f176de",
"sql": "SELECT id, context_length, description FROM models ORDER BY context_length DESC LIMIT 5"
}
}
Example - Custom SQL:
{
"input": {
"operation": "search_models",
"tool_unlock_token": "50f176de",
"sql": "SELECT id, context_length, description, vec_distance_cosine(embedding, vec_f32(:query_vec)) as similarity FROM models WHERE context_length > 32000 ORDER BY similarity LIMIT 5",
"bindings": {"query_vec": {"_embedding_text": "code analysis"}}
}
}
2. list_models: Basic listing of all models with filtering, but NO SORTING. Always pulls data from the API. Always refreshes the DB used by search_models if the API has new/changed/removed models.
Required parameters:
- operation: "list_models"
- tool_unlock_token: (see above)
Optional parameters:
- max_results: Limit number of results
- json: Return full JSON instead of TSV (default false)
- columns: Specific columns to include
- search_criteria: {
"modality": "text->text",
"min_context_length": 32000,
"max_prompt_price": 0.0001,
"max_completion_price": 0.0001,
"provider": "anthropic",
"text_match": "regex pattern",
"case_sensitive": false
}
Example:
{
"input": {
"operation": "list_models",
"tool_unlock_token": "50f176de",
"max_results": 10,
"search_criteria": {
"provider": "anthropic",
"min_context_length": 100000
}
}
}
3. chat_completion: Send chat completion requests
Required parameters:
- operation: "chat_completion"
- tool_unlock_token: (see above)
- model: Model identifier
- messages: Array of message objects
Optional parameters:
- stream: Enable streaming (default false)
- tools: Array of available tools
- tool_choice: Tool selection mode ("none"/"auto"/"any")
Example - Basic Chat:
{
"input": {
"operation": "chat_completion",
"tool_unlock_token": "50f176de",
"model": "anthropic/claude-3-opus",
"messages": [
{"role": "user", "content": "Analyze this code"}
]
}
}
Example - With Source Content:
IMPORTANT: When using source-based messages (file/URL), you MUST precede them with an instruction
message telling the model what to do with the content. The instruction and source should be
separate messages in the array:
{
"input": {
"operation": "chat_completion",
"tool_unlock_token": "50f176de",
"model": "anthropic/claude-3-opus",
"messages": [
{
"role": "user",
"content": "Please analyze this code and explain its main functionality"
},
{
"role": "user",
"content": "https://example.com/code.py",
"source": "url"
}
]
}
}
Example - With File Source:
{
"input": {
"operation": "chat_completion",
"tool_unlock_token": "50f176de",
"model": "anthropic/claude-3-opus",
"messages": [
{
"role": "user",
"content": "Please provide a detailed summary of this chat history"
},
{
"role": "user",
"content": ".specstory/history/latest_chat.md",
"source": "file"
}
]
}
}
4. get_credits: Check account balance
Required parameters:
- operation: "get_credits"
- tool_unlock_token: (see above)
Example:
{
"input": {
"operation": "get_credits",
"tool_unlock_token": "50f176de"
}
}
5. get_generation: Retrieve generation metadata
Required parameters:
- operation: "get_generation"
- tool_unlock_token: (see above)
- generation_id: ID of the generation to retrieve
Example:
{
"input": {
"operation": "get_generation",
"tool_unlock_token": "50f176de",
"generation_id": "gen_abc123"
}
}
Database Schema (openrouter.db):
- id: TEXT PRIMARY KEY (e.g., 'anthropic/claude-3-opus')
- embedding: BLOB (3072-dim vector of the description for semantic search)
- last_updated: DATETIME (auto-refreshes if >24h old)
- description: TEXT (model capabilities and details)
- many other columns (pricing, types, sizes, etc): this table is auto-generated from the OpenRouter list_models result set. search_models by default returns all columns.
IMPORTANT - For Iterative Operations:
When processing multiple models or performing operations that require iterating over the results
(e.g., testing multiple models, analyzing capabilities, or batch processing), consider using the
mcp task_manager tool's long_task operation. This ensures:
- Progress is tracked and persisted
- Operations can be resumed after interruptions
- Context is maintained between iterations
- Clear step-by-step processing instructions are preserved
Notes:
- Database auto-refreshes when needed (24h cache)
- Use search_models for semantic search, list_models for basic filtering
- Vector similarity uses cosine distance (0-1, lower = more similar)
- Forbidden SQL: DELETE, UPDATE, DROP, ALTER, CREATE
- Tool calls supported in chat completions
- Source content can be loaded from URLs, files, or other mcp tool outputs.
Control the ragtag_sse tool-server operation (restart/stop)
Operations:
- get_pid: Get current server's process ID
- stop: Stop the server
- restart: Restart the server
Recommended restart process:
1. Call get_pid to record current PID
2. Call restart operation
3. Use exactly this command for Windows: timeout.exe /t 12 /nobreak
For Mac/Linux use: sleep 12
IMPORTANT: This 12-second wait is required for Cursor to detect the change and reconnect
4. Call get_pid again and verify the new PID is different
If PIDs match, the restart may have failed
5. OPTIONAL: you can see server logs with a powershell command like: Get-Content -Tail 30 "C:\Users\cnd\Downloads\cursor\ragtag\python\ragtag\run_ragtag_sse.log"
Args:
operation: Operation to perform ('restart', 'stop', or 'get_pid')
wait: Optional seconds to wait before operation
system
Parameters Schema
{
"properties": {
"input": {
"type": "object",
"description": "All tool parameters are passed in this single dict. Use {\"input\":{\"operation\":\"readme\"}} to get full documentation, parameters, and an unlock token."
}
},
"required": [],
"type": "object"
}
Windows desktop automation and management tool.
- Use this tool for window management, UI automation, screenshot operations, and desktop layout control
- Call with operation='readme' first to get full documentation and unlock token
Windows Desktop Automation and Management Tool
A comprehensive tool for Windows desktop automation, window management, UI interaction,
and layout control. This tool provides programmatic access to Windows desktop operations
that would typically require manual interaction.
## Usage-Safety Token System
This tool uses an hmac-based token system to ensure callers fully understand all details.
The token is specific to this installation, user, and code version.
Your tool_unlock_token for this installation is: 087ea58f
You MUST include tool_unlock_token in the input dict for all operations.
## Available Operations
### list_windows
List all visible windows with their properties and metadata.
Parameters:
- include_all (optional): Include popup and minimized windows (default: false)
Returns:
- Array of window objects with properties: hwnd, title, class, position, size, style flags
### activate_window
Activate a window by bringing it to the foreground and optionally giving it keyboard focus.
Parameters:
- hwnd (required): Window handle in hexadecimal format (e.g., "0x00020828")
- request_focus (optional): Whether to request keyboard focus in addition to bringing window to front (default: false)
Returns:
- Success message if window was activated successfully
### scan_ui_elements
Scan a specific window and extract all UI elements with text data and coordinates.
This provides 100% accurate text extraction without OCR by accessing Windows accessibility APIs.
Detects accelerator keys (Alt+key shortcuts) and access keys for menu automation.
Uses advanced window finding with multiple fallback strategies for better reliability.
Parameters:
- window_title (optional): Window title or partial title pattern to scan. Uses intelligent matching with fallbacks including exact match, substring match, case-insensitive partial match, and common title variations
- hwnd (optional): Window handle in hexadecimal format (e.g., "0x00020828") for direct window targeting
- NOTE: Either window_title or hwnd must be provided (not both)
Returns:
- Complete UI element tree with text content, coordinates, control types, accelerator keys, and interaction data
### get_clickable_elements
Extract all clickable elements (buttons, links, etc.) from the last scanned window.
Must be called after scan_ui_elements to get clickable element coordinates.
Includes accelerator key information for keyboard automation (e.g., Alt+F for File menu).
Parameters:
- None (uses data from last scan_ui_elements call)
Returns:
- Array of clickable elements with precise coordinates and accelerator key data for automation
### move_window
Move and resize a window to specified position and dimensions.
Parameters:
- hwnd (required): Window handle in hexadecimal format (e.g., "0x00020828")
- x (required): X coordinate for new window position (in pixels)
- y (required): Y coordinate for new window position (in pixels)
- width (required): New window width in pixels
- height (required): New window height in pixels
Returns:
- Success message if window was moved/resized successfully
### click_at_coordinates
Click at specific coordinates within a window (window-relative coordinates).
Parameters:
- hwnd (required): Window handle in hexadecimal format (e.g., "0x00020828")
- x_coordinate (required): X coordinate relative to window (positive = from left, negative = from right)
- y_coordinate (required): Y coordinate relative to window (positive = from top, negative = from bottom)
- button (optional): Mouse button to click ("left", "right", "middle", default: "left")
Returns:
- Success message if click was performed successfully
### click_at_screen_coordinates
Click at absolute screen coordinates (not relative to any window).
Parameters:
- x_coordinate (required): X coordinate on screen (absolute pixels)
- y_coordinate (required): Y coordinate on screen (absolute pixels)
- button (optional): Mouse button to click ("left", "right", "middle", default: "left")
Returns:
- Success message if click was performed successfully
### take_screenshot
Take a screenshot of a window or region of a window.
Parameters:
- hwnd (required): Window handle in hexadecimal format (e.g., "0x00020828")
- filename (optional): Filename to save screenshot to (if not provided, returns base64 image data)
- region (optional): Array [x, y, width, height] specifying region relative to window
Returns:
- Success message and optionally base64 image data if no filename provided
### send_text
Send text input to a window using modern Unicode-compatible SendInput API.
Parameters:
- hwnd (required): Window handle in hexadecimal format (e.g., "0x00020828")
- text (required): Text string to send to the window
Returns:
- Success message if text was sent successfully
### click_ui_element
Click on a specific UI element within a window by name or AutomationId.
Parameters:
- hwnd (required): Window handle in hexadecimal format (e.g., "0x00020828")
- element_name (required): Name or AutomationId of UI element to click
Returns:
- Success message if UI element was clicked successfully
## Input Structure
All parameters are passed in a single 'input' dict:
1. For this documentation:
{
"input": {"operation": "readme"}
}
2. For listing all main windows:
{
"input": {
"operation": "list_windows",
"tool_unlock_token": "087ea58f"
}
}
3. For listing all windows including popups:
{
"input": {
"operation": "list_windows",
"include_all": true,
"tool_unlock_token": "087ea58f"
}
}
4. For activating a specific window:
{
"input": {
"operation": "activate_window",
"hwnd": "0x00020828",
"tool_unlock_token": "087ea58f"
}
}
4b. For activating a window with keyboard focus:
{
"input": {
"operation": "activate_window",
"hwnd": "0x00020828",
"request_focus": true,
"tool_unlock_token": "087ea58f"
}
}
5. For scanning UI elements in a window:
{
"input": {
"operation": "scan_ui_elements",
"window_title": "Notepad",
"tool_unlock_token": "087ea58f"
}
}
5b. For scanning UI elements in a window by handle:
{
"input": {
"operation": "scan_ui_elements",
"hwnd": "0x00020828",
"tool_unlock_token": "087ea58f"
}
}
6. For getting clickable elements from last scan:
{
"input": {
"operation": "get_clickable_elements",
"tool_unlock_token": "087ea58f"
}
}
7. For moving/resizing a window:
{
"input": {
"operation": "move_window",
"hwnd": "0x00020828",
"x": 100,
"y": 100,
"width": 800,
"height": 600,
"tool_unlock_token": "087ea58f"
}
}
8. For clicking at window-relative coordinates:
{
"input": {
"operation": "click_at_coordinates",
"hwnd": "0x00020828",
"x_coordinate": 50,
"y_coordinate": 100,
"button": "left",
"tool_unlock_token": "087ea58f"
}
}
9. For clicking at absolute screen coordinates:
{
"input": {
"operation": "click_at_screen_coordinates",
"x_coordinate": 500,
"y_coordinate": 300,
"tool_unlock_token": "087ea58f"
}
}
10. For taking a screenshot of a window:
{
"input": {
"operation": "take_screenshot",
"hwnd": "0x00020828",
"tool_unlock_token": "087ea58f"
}
}
11. For taking a screenshot of a region within a window:
{
"input": {
"operation": "take_screenshot",
"hwnd": "0x00020828",
"region": [50, 50, 300, 200],
"filename": "screenshot.png",
"tool_unlock_token": "087ea58f"
}
}
12. For sending text to a window:
{
"input": {
"operation": "send_text",
"hwnd": "0x00020828",
"text": "Hello, World!",
"tool_unlock_token": "087ea58f"
}
}
13. For clicking a UI element by name:
{
"input": {
"operation": "click_ui_element",
"hwnd": "0x00020828",
"element_name": "OK",
"tool_unlock_token": "087ea58f"
}
}
```
## Window Object Properties
Each window object contains:
- hwnd: Window handle (hexadecimal string)
- title: Window title text
- class: Window class name
- x, y: Window position coordinates
- width, height: Window dimensions
- style_flags: Window style information
- process_id: Process ID that owns the window
- process_name: Name of the process executable
- is_visible: Whether window is currently visible
- is_minimized: Whether window is minimized
- is_maximized: Whether window is maximized
## Notes
- Window handles (hwnd) are returned as hexadecimal strings for easy use in other operations
- Tool windows and child windows are filtered out by default unless include_all=true
- Process information requires appropriate permissions
task_manager
Parameters Schema
{
"properties": {
"called_readme_operation_in_task_manager": {
"type": "string",
"description": "MANDATORY: Call mcp_ragtag_sse_task_manager using \"operation\":\"readme\" to get the value this parameter requires.",
"default": "not yet"
},
"operation": {
"type": "string",
"enum": [
"read_file_characters",
"readme",
"stat",
"unforget",
"long_task",
"checklist"
],
"description": "Operation to perform; may require an action parameter"
},
"action": {
"type": "string",
"enum": [
"reset",
"status",
"new",
"copy",
"show_lists",
"edit_task_detail",
"mark_done",
"list_items",
"next_item_in_list",
"mark_done_and_get_next_item",
"delete"
],
"description": "Action to perform for long_task or checklist operations"
},
"target_file": {
"type": "string",
"description": "Path to the file to read from"
},
"start_position_in_bytes": {
"type": "integer",
"description": "Position in file to start reading from (0-based)",
"minimum": 0
},
"number_of_characters_to_read": {
"type": "integer",
"description": "Number of characters to read",
"minimum": 1
},
"delimiter_pattern": {
"type": "string",
"description": "Regex pattern for line boundaries. Default '\\n'. Use empty string to disable line completion.",
"default": "\\n"
},
"original_user_query": {
"type": "string",
"description": "The full original that will be converted into step-by-step task instructions by AI"
},
"items": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of items to process (file paths when items_are_files=True, identifiers otherwise)"
},
"items_are_files": {
"type": "boolean",
"description": "When True, items are file paths and character tracking is enabled. When False/omitted, items are simple identifiers.",
"default": false
},
"step_by_step_per_item_task_instructions": {
"type": "string",
"description": "Markdown-formatted instructions for processing each item in direct instructions mode"
},
"ai_help": {
"type": "boolean",
"description": "When True, uses AI to convert user_query into instructions. When False/omitted, uses direct instructions mode.",
"default": false
},
"list_description": {
"type": "string",
"description": "Description of the checklist's purpose"
},
"task_details": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of task detail strings in desired order"
},
"source_list_name": {
"type": "string",
"description": "Name of list to copy"
},
"new_list_name": {
"type": "string",
"description": "Custom name for new list (defaults to list_NN format)"
},
"list_name": {
"type": "string",
"description": "Name of list to modify or display"
},
"item_number": {
"type": "integer",
"description": "Position of item in list (1-based)",
"minimum": 1
},
"new_task_detail": {
"type": "string",
"description": "Updated task description"
}
},
"required": [
"operation",
"called_readme_operation_in_task_manager"
],
"title": "taskManagerArguments",
"type": "object"
}
# Task management system for handling large, long-running, iterative, or multi-step/multi-item operations.
Available operations: readme (use this to learn about all other operations), read_file_characters, stat, checklist, unforget, long_task.
## Use task_manager when ANY of these conditions apply to your task:
- You need to process multiple items in sequence (e.g. files, URLs, AI models, etc.)
- You need to process very large files by reading them in chunks
- The user_query requests you to iterate over any list
- The task might be interrupted
- You need to maintain state between interactions or your context might get exhausted by long or multiple step tasks
- The user expresses concern about forgetting progress
# CRITICAL
- Before ANY use of this tool you *MUST* call operation="readme" first
Task management system for handling long-running operations with state persistence.
Operations:-
# read_file_characters
- read_file_characters: Read exact number of characters from a specific position in a file
Required parameters:
- operation: "read_file_characters"
- target_file: Path to the file to read
- start_position_in_bytes: Position to start reading from (0-based)
- number_of_characters_to_read: How many characters to read
Optional parameters:
- delimiter_pattern: Regex pattern for detecting line boundaries (default: "\n")
When provided, response will be truncated to end at the last complete line
To read raw bytes without line completion, explicitly set to empty string ("")
For minified files that use semicolons, use "[\n;]"
- readme: Get detailed documentation about safe character sizing and context management
Required parameters:
- operation: "readme"
Returns:
- Success response:
* content: Detailed documentation about:
- Context size discovery using OpenRouter
- Safe size calculation formulas
- Fixed and variable costs
- Content type multipliers
- Common configurations
- Best practices
Returns for read_file_characters:
- Success response:
* content: The read characters, truncated to last complete line if delimiter_pattern specified
* bytes_read: Actual number of bytes being returned
* is_last_line_truncated: False if last line is complete (ends with delimiter or at EOF), True otherwise
* is_eof: True if we're at end of file, False otherwise
* encoding: 'utf-8' for text, 'hex' for binary data
* first_line_number: Line number of first line in this chunk (1-based)
* last_line_number: Line number of last line in this chunk (1-based)
Line Number Tracking:
- Line numbers are 1-based (first line is line 1)
- Only LF (
) characters are counted as line separators
- Line numbers are tracked across chunks for consistent numbering
- For binary files (hex encoding), each chunk counts as a single "line"
- When is_last_line_truncated is True, the last line number is decremented
- Error response:
* error: Error message if operation failed
# stat
- stat: Get detailed file information (size, timestamps, type)
Required parameters:
- operation: "stat"
- target_file: Path to file to examine
Returns:
- Success response:
* size: File size in bytes (crucial for read_file_characters planning)
* modified: Last modification time (ISO format)
* accessed: Last access time (ISO format)
* created: Creation time on Windows, inode change time on Unix
* type: File type (file/directory/symlink)
* readable: Whether file is readable by current user
* exists: Whether file exists
Example Usage:
1. Planning file reads:
```python
# First get file size
stat_result = task_manager(operation="stat", target_file="large_file.txt")
total_size = stat_result["size"]
# Then read in chunks
chunk_size = 50000 # Or calculated based on AI context size
for pos in range(0, total_size, chunk_size):
content = task_manager(
operation="read_file_characters",
target_file="large_file.txt",
start_position_in_bytes=pos,
number_of_characters_to_read=min(chunk_size, total_size - pos)
)
```
2. Checking file status:
```python
# Verify file is readable and get its size
info = task_manager(operation="stat", target_file="input.json")
if not info["readable"]:
raise "Cannot read file"
print(f"File size: {info['size']} bytes")
print(f"Last modified: {info['modified']}")
```
3. Size-aware context management:
```python
# Check if file fits in available context
info = task_manager(operation="stat", target_file="code.js")
if info["size"] > my_context_limit:
# Need to read in chunks
chunk_size = calculate_safe_chunk_size()
else:
# Can read entire file
chunk_size = info["size"]
```
# checklist
- checklist: Manage task checklists for tracking progress
Actions:
- new: Create a new checklist
Required parameters:
- operation: "checklist"
- action: "new"
- list_description: Description of the checklist's purpose
- task_details: Array of task detail strings in desired order
Returns: list_name in format list_NN where NN is the checklist_id
- mark_done: Mark a task as completed
Required parameters:
- operation: "checklist"
- action: "mark_done"
- list_name: Name of list containing task
- item_number: Position of item in list (1-based)
Returns: list_name and confirmation
- next_item_in_list: Get next incomplete task
Required parameters:
- operation: "checklist"
- action: "next_item_in_list"
- list_name: Name of list to check
Returns: list_name, description, and next undone item (or completion message with last item)
- mark_done_and_get_next_item: Mark a task as completed and get next item (does mark_done first, then returns next_item_in_list)
- list_items: Show all items in a checklist
Required parameters:
- operation: "checklist"
- action: "list_items"
- list_name: Name of list to display
Returns: list_name, description, and numbered list of all items with done status
- copy: Duplicate an existing checklist (not including the is_done status, which will always be False in the new list)
Required parameters:
- operation: "checklist"
- action: "copy"
- source_list_name: Name of list to copy
Optional parameters:
- new_list_name: Custom name for new list (defaults to list_NN format)
Returns: New list_name and description
- show_lists: Display all checklists
Required parameters:
- operation: "checklist"
- action: "show_lists"
Optional parameters:
- limit: Maximum lists to return (default 50)
Returns: Array of {list_name, list_description} ordered by most recent first
- edit_task_detail: Update a task's description
Required parameters:
- operation: "checklist"
- action: "edit_task_detail"
- list_name: Name of list to modify
- item_number: Position of item in list (1-based)
- new_task_detail: Updated task description
Returns: list_name and updated task detail
- reset: Clear all done flags in a checklist
Required parameters:
- operation: "checklist"
- action: "reset"
- list_name: Name of list to reset
Returns: list_name and confirmation
- delete: remove a checklist
Required parameters:
- operation: "checklist"
- action: "delete"
- list_name: Name of list to delete
Example Usage
1. Create new checklist:
Example Usage:
1. Create new checklist:
```json
{
"operation": "checklist",
"action": "new",
"list_description": "Steps to deploy new feature",
"task_details": [
"Update dependencies",
"Run tests",
"Build release",
"Deploy to staging",
"Verify staging",
"Deploy to production"
]
}
```
2. Copy existing checklist:
```json
{
"operation": "checklist",
"action": "copy",
"source_list_name": "list_42",
"new_list_name": "deployment_march" # Optional
}
```
3. Get next task:
```json
{
"operation": "checklist",
"action": "next_item_in_list",
"list_name": "list_42"
}
```
4. Mark task complete:
```json
{
"operation": "checklist",
"action": "mark_done",
"list_name": "list_42",
"item_number": 3
}
```
Notes:
- All operations return the list_name to maintain context
- Item numbers are 1-based for human readability
- Lists are stored persistently in SQLite
- Task details can be refined/improved as you work
- Progress is maintained across context losses
# unforget
- unforget: Get instructions for recovering lost context from chat history
Required parameters:
- operation: "unforget"
Returns:
- Success response:
* content: Step-by-step instructions for recovering context:
1. Find newest .specstory/history/ file
2. Use openrouter to find model with largest context
3. Use chat_completion with source:file to upload history
4. Get detailed summary of chat history and current state
# long_task
- long_task: Manage tasks that span multiple interactions or exceed context limits
## CRITICAL: Task Creation and Management Flow
- If you have been asked to use this tool, but not asked to work on creating a brand new task, then the user is asking you to Start or Resume an existing Task.
## Understanding the Single-Task Limitation
IMPORTANT: This tool supports only ONE active task at a time. Here's why:
- This tool is specifically designed for AI agents that have LOST ALL CONTEXT
- When an AI loses context, it has no way to know which of multiple tasks was being worked on
- Each new AI instance needs clear, unambiguous instructions about exactly ONE task
- Multiple AIs might start processing the same task independently after context loss
- Having multiple tasks would create confusion and potential data corruption
Think of it as a recovery system - it assumes any AI using it might have just "woken up"
with no memory of what it was doing before.
## Task Operations:
1. Start or Resume an existing Task:
```json
{
"operation": "long_task"
}
```
- No additional parameters needed
- Automatically finds the current task, progress, and next item
- Returns instructions and the next item to process
2. Check Status:
```json
{
"operation": "long_task",
"action": "status"
}
```
3. Create New Task (only do this when you are SURE the user explicitly asked for a new long_task in a new ):
- First - check existing task status; if it's not complete, double-check with the user that they want to delete that task.
- Then, call Reset to erase all existing old task data (REQUIRED before creating any new task):
```json
{
"operation": "long_task",
"action": "reset"
}
```
- Then, create a new task with all required parameters:
- Required parameters:
* items: Array of items to process (file paths or string identifiers)
* PLUS EITHER:
- step_by_step_per_item_task_instructions: Detailed instructions (when ai_help=false)
- original_user_query: Raw user request (when ai_help=true)
- Optional parameters:
* items_are_files: true for file processing, false for simple item processing
* ai_help: true to auto-generate instructions from user_query
This operation helps when:
1. Processing multiple items sequentially (files or other items)
2. Working through very large files in chunks (when items_are_files=True)
3. Handling tasks that need progress tracking
4. Tasks likely to be interrupted
5. Operations that may exceed context limits
Task Instructions - Two Modes:
1. Direct Instructions Mode (ai_help=false):
- step_by_step_per_item_task_instructions: Required markdown-formatted instructions including:
* What needs to be done FOR EACH ITEM - focus on single-item processing
* The tool handles iteration and progress tracking automatically
* You will receive one item at a time to process
* Include:
- Exact steps to process a single item or chunk
- How to handle that specific item or chunk
- Where/how to save any output
- What indicates success for that item
* Recovery procedures if item processing is interrupted
2. AI-Assisted Mode (ai_help=true):
- original_user_query: Required. The **COMPLETE** text between tags. It will be:
* Converted into detailed step-by-step instructions by AI
* Must include all context and requirements
* Will be preserved exactly as provided
* AI will structure this into clear processing steps
* No need to format as instructions - the AI handles that
Common Parameters (Both Modes):
- items: REQUIRED list of items to process. Each item must be either:
* When items_are_files=True: A valid file path that will be read in chunks
* When items_are_files=False: Any string identifier meaningful to your task
IMPORTANT: Must include ALL items upfront - cannot add more items later
- items_are_files: Optional boolean. When True:
* Each item in 'items' must be a file path
* Character position tracking is enabled
* Chunked reading is supported
When False/omitted:
* Items are treated as simple identifiers
* Only completion status is tracked
- ai_help: Optional boolean. When True:
* Uses AI to convert user_query into instructions
* Requires original_user_query parameter in full
When False/omitted:
* Uses direct instructions mode
* Requires step_by_step_per_item_task_instructions parameter
State Tracking:
- For files (items_are_files=True):
* Tracks character position in each file
* Supports chunked reading, without returning truncated/partial lines
* Maintains reading progress
- For other items (items_are_files=False):
* Only tracks completion status (done/not done)
* No additional state maintained
File Path Handling:
- When generating output filenames from non-file-based item identifiers:
* REQUIRED: Convert characters using these rules:
1. Keep all Unicode letters and numbers (including non-Latin scripts)
2. Keep safe punctuation: dots (.), hyphens (-), underscores (_)
3. Replace all other characters with underscore (_)
4. Collapse multiple consecutive underscores into one
5. Remove leading/trailing underscores
* This ensures filenames:
- Support international text (UTF-8)
- Are valid on all operating systems
- Don't contain path traversal characters
- Preserve human readability
* Example transformations:
- "google/gemini-pro" → "google_gemini-pro"
- "안녕하세요/모델-1" → "안녕하세요_모델-1" # Unicode support example
- Complex example:
Input: http://example.com/~user.htm?search=my`dangerous file`*&opt='"do%20search"'
Output: http_example.com_user.htm_search_my_dangerous_file_opt_do_search
Example Usage to create a new long_task:
1. Direct Instructions Mode (ai_help=false):
```json
{
"operation": "long_task",
"action": "reset"
}
```
Then:
```json
{
"operation": "long_task",
"step_by_step_per_item_task_instructions": "# Task: Process Log Files\n1. For each file in the list:\n - Read the file\n - Extract timestamps\n - Save to output.csv\n2. Success when all files processed",
"items": ["log1.txt", "log2.txt"],
"items_are_files": true,
"ai_help": false
}
```
2. AI-Assisted Mode to create a new long_task (ai_help=true):
```json
{
"operation": "long_task",
"action": "reset"
}
```
Then:
```json
{
"operation": "long_task",
"original_user_query": "For each OpenRouter model that can write code, ask them to return this:-\n\nA python program to draw a smooth text-based love-heart using full screen width\n(or height, whichever is most appropriate given the available aspect ratio),\nusing no other import besides os\n\nwrite the output of each into the file named ./python/ragtag/src/ragtag/tests/hearts-{model_id}.py",
"items": ["anthropic/claude-3", "google/gemini-pro"],
"ai_help": true
}
```
3. Start or Resuming after interruption (may also be used in parallel when it makes sense for multiple agents to work on tasks independently):
```json
{
"operation": "long_task"
}
```
4. Checking progress:
```json
{
"operation": "long_task",
"action": "status"
}
```
5. Clearing existing task:
```json
{
"operation": "long_task",
"action": "reset"
}
```
Key Features:
- Maintains own state in SQLite database
- Tracks progress automatically
- Provides clear next steps
- Handles interruptions gracefully
- Self-documents task requirements
- Manages file positions precisely
- Optional AI assistance for task structuring
Best Practices:
1. Choose mode based on task complexity:
- Use ai_help=true for complex tasks needing structured breakdown (when using this mode: try not to shorten or omit any of the user_query instructions from their original input.)
- Use ai_help=false when you already have clear step-by-step instructions
2. Let the tool handle iteration and progress tracking
3. Include recovery procedures for individual items
4. Define clear per-item success criteria
5. Specify output formats and locations
6. List any assumptions about item processing
IMPORTANT: **Expect** that, in the middle of processing any item, you will forget **everything** about what you are doing.
The instructions (whether AI-generated or direct) MUST provide every bit of context needed to successfully process each individual item to completion.
The operation will guide you through:
- What to do next
- Current progress
- Remaining work
- Any errors or issues
- Recovery steps if needed
# called_readme_operation_in_task_manager
- Set this to exactly "YES!" to confirm you have read and understood all this tool's documentation.
template
Parameters Schema
{
"properties": {
"input": {
"type": "object",
"description": "All tool parameters are passed in this single dict. Use {\"input\":{\"operation\":\"readme\"}} to get full documentation, parameters, and an unlock token."
}
},
"required": [],
"type": "object"
}
Echo back the input text.
- Use this tool when you need to echo text back (e.g. when testing tool-call infrastructure itself)
Echo back the input text.
A simple tool for echoing back input text. This tool provides a template
for implementing MCP tools with an optimized input pattern with a usage-safety token.
## Usage-Safety Token System
This tool uses an hmac-based token system to ensure callers fully understand all details of
using this tool, on every call. The token is specific to this installation, user, and code version.
Your tool_unlock_token for this installation is: 062da367
You MUST include tool_unlock_token in the input dict for all operations.
## Input Structure
All parameters are passed in a single 'input' dict:
1. For this documentation:
{
"input": {"operation": "readme"}
}
2. For echo operation:
{
"input": {
"operation": "echo",
"text": "Text to echo back",
"tool_unlock_token": "062da367"
}
}
## Usage Notes
1. Include the tool_unlock_token in all subsequent operations
2. Text parameter is required for echo operation
3. Maximum text length is not restricted
4. Returns the exact text provided
## Examples
```json
{
"input": {
"operation": "echo",
"text": "Always include an exhaustive set of examples demonstrating all parameters and features of new tools you write based on this template, in the format that an AI needs to use to make the tool call.",
"tool_unlock_token": "062da367"
}
}
```
adaptive_thinking
Parameters Schema
{
"type": "object",
"title": "adaptive_thinkingArguments",
"properties": {
"called_readme_operation_in_adaptive_thinking": {
"type": "string",
"description": "MANDATORY: Call mcp_ragtag_sse_mcp_adaptive_thinking using \"operation\":\"readme\" to get the value this paramater requires.",
"default": "not yet"
},
"operation": {
"type": "string",
"enum": [
"readme"
],
"description": "use this to get instructions"
},
"thought": {
"type": "string",
"description": "Your current thinking step"
},
"nextThoughtNeeded": {
"type": "boolean",
"description": "Whether another thought step is needed"
},
"thoughtNumber": {
"type": "integer",
"description": "Current thought number",
"minimum": 1
},
"totalThoughts": {
"type": "integer",
"description": "Estimated total thoughts needed",
"minimum": 1
},
"isRevision": {
"type": "boolean",
"description": "Whether this revises previous thinking"
},
"revisesThought": {
"type": "integer",
"description": "Which thought is being reconsidered",
"minimum": 1
},
"branchFromThought": {
"type": "integer",
"description": "Branching point thought number",
"minimum": 1
},
"branchId": {
"type": "string",
"description": "Branch identifier"
},
"needsMoreThoughts": {
"type": "boolean",
"description": "If more thoughts are needed"
}
}
}
Task management system for dynamic and reflective problem-solving through adaptive thinking.
Use this tool when tackling complex problems that may need revision, branching, or course correction as understanding deepens.
# CRITICAL
- Before ANY use of this tool you *MUST* call operation="readme" first
Adaptive Thinking Tool - Detailed Documentation
A detailed tool for dynamic and reflective problem-solving through thoughts.
This tool helps analyze problems through a flexible thinking process that can adapt and evolve.
Each thought can build on, question, or revise previous insights as understanding deepens.
When to use this tool:
- Breaking down complex problems into steps
- Planning and design with room for revision
- Analysis that might need course correction
- Problems where the full scope might not be clear initially
- Problems that require a multi-step solution
- Tasks that need to maintain context over multiple steps
- Situations where irrelevant information needs to be filtered out
Key features:
- You can adjust total_thoughts up or down as you progress
- You can question or revise previous thoughts
- You can add more thoughts even after reaching what seemed like the end
- You can express uncertainty and explore alternative approaches
- Not every thought needs to build linearly - you can branch or backtrack
- Generates a solution hypothesis
- Verifies the hypothesis based on the Chain of Thought steps
- Repeats the process until satisfied
- Provides a correct answer
Parameters explained:
- thought: Your current thinking step, which can include:
* Regular analytical steps
* Revisions of previous thoughts
* Questions about previous decisions
* Realizations about needing more analysis
* Changes in approach
* Hypothesis generation
* Hypothesis verification
- nextThoughtNeeded: True if you need more thinking, even if at what seemed like the end
- thoughtNumber: Current number in sequence (can go beyond initial total if needed)
- totalThoughts: Current estimate of thoughts needed (can be adjusted up/down)
- isRevision: A boolean indicating if this thought revises previous thinking
- revisesThought: If isRevision is true, which thought number is being reconsidered
- branchFromThought: If branching, which thought number is the branching point
- branchId: Identifier for the current branch (if any)
- needsMoreThoughts: If reaching end but realizing more thoughts needed
You should:
1. Start with an initial estimate of needed thoughts, but be ready to adjust
2. Feel free to question or revise previous thoughts
3. Don't hesitate to add more thoughts if needed, even at the "end"
4. Express uncertainty when present
5. Mark thoughts that revise previous thinking or branch into new paths
6. Ignore information that is irrelevant to the current step
7. Generate a solution hypothesis when appropriate
8. Verify the hypothesis based on the Chain of Thought steps
9. Repeat the process until satisfied with the solution
10. Provide a single, ideally correct answer as the final output
11. Only set nextThoughtNeeded to false when truly done and a satisfactory answer is reached
- Set called_readme_operation_in_mcp_template to exactly "Yes!" to confirm you have read and understood this documentation
Parameters required: ["thought", "nextThoughtNeeded", "thoughtNumber", "totalThoughts", "called_readme_operation_in_adaptive_thinking"]
tts
Parameters Schema
{
"properties": {
"called_readme_operation_in_tts": {
"type": "string",
"description": "MANDATORY: Call mcp_ragtag_sse_tts using \"operation\":\"readme\" to get the value this paramater requires.",
"default": "not yet"
},
"operation": {
"type": "string",
"enum": [
"speak",
"save",
"list_voices",
"get_voice_settings",
"get_models",
"readme"
],
"description": "Operation to perform"
},
"provider": {
"type": "string",
"enum": [
"google",
"elevenlabs",
"deepgram"
],
"description": "TTS provider to use",
"default": "google"
},
"text": {
"type": "string",
"description": "Text to convert to speech (required for speak/save operations)",
"maxLength": 8192
},
"voice_id": {
"type": "string",
"description": "Voice identifier (required for speak/save operations)"
},
"model_id": {
"type": "string",
"description": "Model to use (defaults to provider's recommended model)"
},
"output_format": {
"type": "string",
"enum": [
"mp3_44100_128",
"mp3_22050_32"
],
"description": "Audio format (mp3_44100_128 for quality, mp3_22050_32 for low latency)",
"default": "mp3_22050_32"
},
"voice_settings": {
"type": "object",
"description": "Voice customization parameters",
"properties": {
"stability": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0,
"description": "Voice stability"
},
"similarity_boost": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0,
"description": "Similarity boost factor"
},
"style": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0,
"description": "Style factor"
},
"use_speaker_boost": {
"type": "boolean",
"description": "Whether to use speaker boost"
},
"speed": {
"type": "number",
"minimum": 0.1,
"maximum": 5.0,
"description": "Speaking speed multiplier"
}
}
},
"save_path": {
"type": "string",
"description": "Path to save audio file (required for save operation)"
}
},
"required": [
"operation"
],
"title": "ttsArguments",
"type": "object"
}
Text to Speech synthesis tool.
- Use this when you need to convert text to speech
- the speech comes out the PC speakers.
- IMPORTANT: Before using this tool: call "operation":"readme" for full instructions
Text to Speech synthesis tool supporting multiple providers.
Currently supports:
- Google Cloud (provider="google")
- ElevenLabs (provider="elevenlabs")
- Deepgram (provider="deepgram")
## Operations
- speak: Convert text to speech and play directly to speakers
- save: Convert text to speech and save to file
- list_voices: Get available voices for a provider
- get_voice_settings: Get customizable settings for a voice
- get_models: List available models and their capabilities
Features:
- Multiple output formats (mp3_44100_128 for high quality, mp3_22050_32 for low latency)
- Voice customization (stability, similarity boost, style, speed)
- Non-blocking audio playback
- Optional file saving
- Comprehensive voice and model information for AI decision making
### Get Documentation (`operation="readme"`)
- Returns the complete tool documentation
- Must be called before using any other operations
- Set called_readme_operation_in_tts to exactly "YYY!" to confirm you have read and understood this documentation
### List Voices (`operation="list_voices"`)
- Get available voices for a provider
- Optional: provider parameter to specify which TTS service to use
### Get Voice Settings (`operation="get_voice_settings"`)
- Get customizable settings for a specific voice
- Required: voice_id parameter
- Optional: provider parameter
### Get Models (`operation="get_models"`)
- List available models and their capabilities
- Optional: provider parameter
### Speak Text (`operation="speak"`)
- Convert text to speech and play directly to speakers
- Required parameters:
* text: The text to convert (max 8KB)
* voice_id: Voice identifier
- Optional parameters:
* provider: TTS provider to use
* model_id: Specific model to use
* output_format: "mp3_44100_128" (high quality) or "mp3_22050_32" (low latency)
* voice_settings: Customization parameters (stability, similarity_boost, style, speed)
### Save Audio (`operation="save"`)
- Convert text to speech and save to file
- Required parameters:
* text: The text to convert (max 8KB)
* voice_id: Voice identifier
* save_path: Where to save the audio file
- Optional parameters:
* provider: TTS provider to use
* model_id: Specific model to use
* output_format: "mp3_44100_128" (high quality) or "mp3_22050_32" (low latency)
* voice_settings: Customization parameters
## Authentication
- Google Cloud: Set GOOGLE_APPLICATION_CREDENTIALS environment variable
- ElevenLabs: Set ELEVENLABS_API_KEY environment variable
- Deepgram: Set DEEPGRAM_API_KEY environment variable
## Proceedure for AI:
1. First call get_models to understand available capabilities
2. Then list_voices to get available voices
3. For chosen voice, use get_voice_settings to understand customization options
4. Finally use speak or save with your chosen configuration
## Example Usage
```python
# First get documentation
{
"operation": "readme",
"provider": "google"
}
# List available voices
{
"operation": "list_voices",
"provider": "google",
"called_readme_operation_in_tts": "YYY!"
}
# Get voice settings
{
"operation": "get_voice_settings",
"provider": "google",
"voice_id": "en-US-Standard-A",
"called_readme_operation_in_tts": "YYY!"
}
# Speak text
{
"operation": "speak",
"provider": "google",
"text": "Hello, world!",
"voice_id": "en-US-Standard-A",
"voice_settings": {
"stability": 0.5,
"similarity_boost": 0.75,
"speed": 1.0
},
"called_readme_operation_in_tts": "YYY!"
}
Note: Maximum text length is 8192 bytes (8KB)
# Save to file
{
"operation": "save",
"provider": "google",
"text": "Hello, world!",
"voice_id": "en-US-Standard-A",
"save_path": "output.wav",
"called_readme_operation_in_tts": "YYY!"
}
```
Generate a 3072-dimensional vector embedding for input text using Google's Gemini model.
Features:
- Automatic local caching of embeddings
- Thread-safe concurrent access
- Exact text matching for cache hits
- SSL certificate verification disabled (for restricted environments)
- Supports IP address override via GEMINI_API_HOST environment variable
Environment Variables:
- GEMINI_API_KEY: Required API key for Gemini service
- GEMINI_API_HOST: Optional host override (use IP if DNS blocked)
Args:
text: The input text to generate embeddings for
Get weather forecast for a location.
Args:
latitude: Latitude of the location
longitude: Longitude of the location
webview
Parameters Schema
{
"properties": {
"input": {
"type": "object",
"description": "All tool parameters are passed in this single dict. Use {\"input\":{\"operation\":\"readme\"}} to get full documentation, parameters, and an unlock token."
}
},
"required": [],
"type": "object"
}
Opens a native-desktop, interactive, popup user-dialog window with optional modal-attachment, topmost, and other features to show arbitrary HTML or URLs to users.
- Use this tool to show rich user-interfaces to users and/or collect responses or input from them.
Native Desktop WebView Window Tool
Creates native desktop windows displaying HTML content or web URLs with extensive customization options.
Perfect for AI assistants to show rich user interfaces, forms, and interactive content.
## Usage-Safety Token System
This tool uses an hmac-based token system to ensure callers fully understand all details.
The token is specific to this installation, user, and code version.
Your tool_unlock_token for this installation is: f05eb586
You MUST include tool_unlock_token in the input dict for all operations.
## Operations
### 1. Get Documentation
{
"input": {"operation": "readme"}
}
### 2. Open Window (with HTML content)
{
"input": {
"operation": "open",
"html": "
",
"wait_for_close": true,
"tool_unlock_token": "f05eb586"
}
}
### 6. Close Window
{
"input": {
"operation": "close",
"window_id": 1,
"tool_unlock_token": "f05eb586"
}
}
## Content Parameters (exactly one required)
- `html`: HTML content string to display in the window
- `url`: Web URL to load in the window
Note: If both are provided, `html` takes precedence and `url` is ignored.
## Display Parameters (all optional with sensible defaults)
- `title`: Window title shown in title bar (default: "Aura Friday's mcp-Link")
- `width`: Window width in pixels (default: 800)
- `height`: Window height in pixels (default: 600)
- `center`: Center window on screen automatically (default: true)
- `background_color`: Background color of HTML content area as hex color (default: "#FFFFFF"). This does NOT affect window title bar color, only the web page background.
## Window Positioning
- `x`, `y`: Explicit window position in pixels from top-left of screen. When provided, overrides `center=true`.
- `screen`: Screen index for multi-monitor setups (0=primary monitor, 1=secondary, etc.). Window appears on specified monitor.
## Size Constraints
- `min_width`: Minimum window width in pixels (default: 1) - allows for tiny indicator windows
- `min_height`: Minimum window height in pixels (default: 1) - allows for tiny indicator windows
- `resizable`: Allow user to resize window by dragging edges (default: true)
## Window States
- `hidden`: Create window but don't show it initially - useful for pre-loading content (default: false)
- `minimized`: Start window minimized to taskbar (default: false)
- `maximized`: Start window maximized to fill screen (default: false)
- `fullscreen`: Start in fullscreen mode with no window borders or title bar (default: false)
## Behavior Parameters
- `wait_for_close`: Block and wait for user to close window, then return detailed close information (default: false)
- `modal`: Create modal dialog that blocks input to parent window until closed. ONLY works when `parent_handle` is provided. (default: false)
- `on_top`: Keep window always on top of ALL other windows system-wide (default: false)
- `confirm_close`: Show "Are you sure?" dialog when user tries to close window (default: false)
## Parent-Child Window Relationships
- `parent_handle`: Windows HWND handle of parent window (format: "HWND_12345"). When provided:
- This window appears on top of everything inside the parent window
- Other non-parent windows can still appear on top of this window
- Required for `modal=true` functionality
- Creates parent-child relationship for window management
## Appearance Parameters
- `transparent`: Make window background transparent - content with transparent CSS will show through. Not supported on Windows. (default: false)
- `frameless`: Remove title bar AND window borders - creates borderless window (default: false)
- `shadow`: Add drop shadow around window - Windows only feature (default: true)
- `icon`: Path to icon file (.ico, .png) to show in title bar and taskbar (default: attempts "../webview.ico")
## Content Interaction Controls
- `text_select`: Allow users to select and copy text from the web content (default: false)
- `zoomable`: Allow users to zoom in/out on web content using Ctrl+scroll or zoom controls (default: false)
- `draggable`: Allow users to drag images and links FROM the window to other applications (default: false)
## Technical Parameters
- `private_mode`: Enable private browsing - no cookies, history, or cache saved between sessions (default: false)
- `debug`: Enable developer tools (F12) for debugging HTML/JavaScript content (default: false)
- `user_agent`: Custom User-Agent string sent to websites - useful for compatibility or identification (default: system default)
## Return Values
### Immediate Return (wait_for_close=false)
{
"window_id": 1,
"native_id": "HWND_12345",
"status": "opened",
"created_at": "2025-01-XX 10:30:45"
}
### Wait Return (wait_for_close=true)
{
"window_id": 1,
"native_id": "HWND_12345",
"status": "closed",
"created_at": "2025-01-XX 10:30:45",
"closed_at": "2025-01-XX 10:32:15",
"duration_seconds": 90,
"close_reason": "user_closed"
}
## Error Handling
All errors are logged to console. Common issues:
- PyWebView not installed: `pip install pywebview`
- Platform limitations (transparency on Windows, etc.)
- Invalid HTML syntax or unreachable URLs
- Invalid parameter combinations (e.g., modal=true without parent_handle)
- Invalid hex colors for background_color
## Platform Notes
- **Windows**: Full feature support, uses EdgeWebView2 engine
- **macOS**: Most features supported, uses WebKit engine
- **Linux**: Feature support varies by desktop environment (GTK/Qt)
## Examples for Common Use Cases
### File Upload Form
{
"input": {
"operation": "open",
"html": "",
"title": "Select Files",
"width": 500,
"height": 300,
"modal": true,
"parent_handle": "HWND_12345",
"tool_unlock_token": "f05eb586"
}
}
### Information Display with Custom Styling
{
"input": {
"operation": "open",
"html": "
{
"properties": {
"operation": {
"type": "string",
"enum": [
"test",
"search_contacts",
"get_last_interaction",
"list_chats",
"send_message",
"get_messages"
],
"description": "Operation to perform"
},
"message": {
"type": "string",
"description": "Test message to echo back"
},
"query": {
"type": "string",
"description": "Search term to match against contact names or phone numbers"
},
"jid": {
"type": "string",
"description": "The JID of the contact or group to interact with"
},
"text": {
"type": "string",
"description": "Message text to send"
},
"chat_jid": {
"type": "string",
"description": "The JID of the chat to get messages from"
},
"last_seen_timestamp": {
"type": "string",
"description": "Timestamp string in format (e.g.) 2025-03-30 17:13:30+10:00. If not provided, returns last N messages"
},
"wait": {
"type": "number",
"description": "Number of seconds to wait for new messages (recommended: 270)",
"default": 0
},
"limit": {
"type": "integer",
"description": "Maximum number of messages to return if last_seen_timestamp is None",
"default": 20
},
"include_last_message": {
"type": "boolean",
"description": "Whether to include the last message in results",
"default": true
},
"sort_by": {
"type": "string",
"description": "Field to sort results by",
"enum": [
"last_active",
"name"
],
"default": "last_active"
}
},
"required": [
"operation"
],
"title": "whatsappArguments",
"type": "object"
}
WhatsApp messaging functionality.
Operations:
- test: Simple test operation to verify tool functionality
- search_contacts: Search for contacts by name or phone number
- get_last_interaction: Get most recent message involving the contact
- list_chats: Get WhatsApp chats matching specified criteria
- send_message: Send a message to any chat (personal or group)
- get_messages: Get messages with optional waiting for new ones
whereami
Parameters Schema
{
"properties": {
"input": {
"type": "object",
"description": "All tool parameters are passed in this single dict. Use {\"input\":{\"operation\":\"readme\"}} to get full documentation, parameters, and an unlock token."
}
},
"required": [],
"type": "object"
}
Get user's IP-address geo-location (lat/lon, city,state,country, ISP, Nearby cities, map URLs, and culturally-appropriate sample male and female names.
Get user's geo-location with extras.
This tool provides comprehensive location information including geographical coordinates,
administrative boundaries, ISP details, nearby cities, and culturally appropriate names
for the detected region.
## Usage-Safety Token System
This tool uses an hmac-based token system to ensure callers fully understand all details of
using this tool, on every call. The token is specific to this installation, user, and code version.
Your tool_unlock_token for this installation is: 91be97a8
You MUST include tool_unlock_token in the input dict for all operations.
## Input Structure
All parameters are passed in a single 'input' dict:
1. For this documentation:
{
"input": {"operation":"readme"}
}
2. For get_location operation:
{
"input": {
"operation": "get_location",
"tool_unlock_token": "91be97a8"
}
}
## Operations
### Get Documentation (`operation="readme"`)
- Returns this documentation and the unlock token
- No additional parameters required
### Get Location (`operation="get_location"`)
- Retrieves comprehensive location data based on the user's IP address
- Requires tool_unlock_token parameter
- Returns detailed geographical, network, and cultural information
## Return Data Structure
The tool returns a comprehensive JSON object containing:
### Basic Location
- `latitude`: Geographic latitude coordinate
- `longitude`: Geographic longitude coordinate
- `city`: Current city name
- `state`: State/province/region name
- `country`: Full country name
- `country_code`: ISO country code
### Network Information
- `ip_address`: Public IP address used for location detection
- `isp_name`: Internet Service Provider name
- `connection_type`: Connection speed/type information
- `autonomous_system`: AS number and organization
- `is_proxy`: Boolean indicating if connection appears to be through a proxy
### Geographic Context
- `nearby_cities`: Array of nearby cities with coordinates and names
- `confidence_percent`: Accuracy confidence level (0-100)
### Cultural Context
- `cultural_names`: Object containing culturally appropriate names for the region
- `female_names`: Array of common female names in the region
- `male_names`: Array of common male names in the region
### Map Resources
- `map_image_url`: URL to a static map image of the location
- `interactive_map_url`: URL to an interactive map centered on the location
## Usage Notes
1. Always call readme operation first to get the unlock token
2. Location detection is based on IP geolocation and may not be 100% accurate
3. Proxy/VPN usage may affect location accuracy
4. Cultural names are provided for creative/contextual purposes
5. Map URLs are provided for visualization purposes
6. Include the tool_unlock_token in all subsequent operations
## Privacy Notes
- This tool uses external services to determine location
- Only IP-based geolocation is used (no GPS or device location)
- No personal data is stored or transmitted beyond what's necessary for geolocation
## Examples
```json
# Get documentation and token
{
"input": {"operation":"readme"}
}
# Get current location information
{
"input": {
"operation": "get_location",
"tool_unlock_token": "91be97a8"
}
}
```
## Sample Response
```json
{
"latitude": 37.7749,
"longitude": -122.4194,
"city": "San Francisco",
"state": "California",
"country": "United States",
"country_code": "US",
"ip_address": "192.168.1.1",
"isp_name": "Example ISP",
"connection_type": "Cable/DSL",
"autonomous_system": "AS12345 Example Networks",
"is_proxy": false,
"nearby_cities": [
{
"latitude": 37.8044,
"longitude": -122.2711,
"city_name": "Oakland",
"region": "California"
}
],
"cultural_names": {
"female_names": ["Jennifer", "Jessica", "Ashley"],
"male_names": ["Michael", "Christopher", "Matthew"]
},
"confidence_percent": 85,
"map_image_url": "https://example.com/map.png",
"interactive_map_url": "https://example.com/interactive-map"
}
```
Cursor IDE Configuration
Copy these settings to your Cursor IDE MCP configuration file at ~/.cursor/mcp.json: