admin-valentin/arcade-mcp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Remove arcade docs CLI command - moved to the 'ArcadeAI/docs' repo (#642)

Browse source
This commit is contained in:
Renato Byrro 2025-10-22 14:04:09 -03:00 committed by GitHub
parent ba1b2e6788
commit 4dfd0522a6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 0 additions and 1418 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

110
libs/arcade-cli/arcade_cli/main.py
View file

@ -27,7 +27,6 @@ from arcade_cli.display import (
display_eval_results,
)
from arcade_cli.show import show_logic
from arcade_cli.toolkit_docs import generate_toolkit_docs
from arcade_cli.usage.command_tracker import TrackedTyper, TrackedTyperGroup
from arcade_cli.utils import (
Provider,
@ -707,115 +706,6 @@ def dashboard(
handle_cli_error("Failed to open dashboard", e, debug)
@cli.command(
help=(
"Generate documentation for a server. "
"Note: make sure to have the server installed in your current Python environment "
"before running this command."
),
rich_help_panel="Document",
hidden=True,
)
def docs(
server_name: str = typer.Option(
...,
"--server-name",
"-n",
help="The name of the server to generate documentation for.",
),
server_dir: str = typer.Option(
...,
"--server-dir",
"-t",
help=(
"The path to the server root directory (where the server code is implemented). "
"Works with relative and absolute paths."
),
),
docs_dir: str = typer.Option(
...,
"--docs-dir",
"-r",
help="The path to the root of the Arcade docs repository. Works with relative and absolute paths.",
),
docs_section: str = typer.Option(
"",
"--docs-section",
"-s",
help=(
"The section of the docs to generate documentation for. E.g. 'productivity', 'sales'. "
"This should be the name of the folder in /pages/tools. "
"Defaults to an empty string (generate the docs in the root of /pages/tools)"
),
),
openai_model: str = typer.Option(
"gpt-5-mini",
"--openai-model",
"-m",
help=(
"A few parts of the documentation are generated using OpenAI API. "
"Choose one of the 'gpt-4o' and 'gpt-5' series models."
),
show_default=True,
),
openai_api_key: str = typer.Option(
None,
"--openai-api-key",
"-o",
help="The OpenAI API key. If not provided, will get it from the `OPENAI_API_KEY` env var.",
),
skip_tool_call_examples: bool = typer.Option(
False,
"--skip-tool-call-examples",
"-se",
help="Whether to skip generating tool call examples in Python and Javascript.",
show_default=True,
),
debug: bool = typer.Option(False, "--debug", "-d", help="Show debug information"),
) -> None:
if not openai_model.startswith("gpt-4o") and not openai_model.startswith("gpt-5"):
console.print(
f"Attention: '{openai_model}' is not a valid OpenAI model. "
"Please choose one of the 'gpt-4o' and 'gpt-5' series models.",
style="bold red",
)
handle_cli_error(
f"Attention: '{openai_model}' is not a valid OpenAI model. "
"Please choose one of the 'gpt-4o' and 'gpt-5' series models."
)
try:
success = generate_toolkit_docs(
console=console,
toolkit_name=server_name,
toolkit_dir=server_dir,
docs_dir=docs_dir,
docs_section=docs_section,
openai_model=openai_model,
openai_api_key=openai_api_key,
tool_call_examples=not skip_tool_call_examples,
debug=debug,
)
except Exception as error:
handle_cli_error(
message=f"Failed to generate documentation for '{server_name}' in '{docs_dir}'",
error=error,
debug=debug,
)
success = False
if success:
console.print(
f"Generated documentation for '{server_name}' in '{docs_dir}'",
style="bold green",
)
else:
console.print(
f"Failed to generate documentation for '{server_name}' in '{docs_dir}'",
style="bold red",
)
@cli.callback()
def main_callback(
ctx: typer.Context,

85
libs/arcade-cli/arcade_cli/toolkit_docs/__init__.py
View file

@ -1,85 +0,0 @@
from functools import partial
import openai
from rich.console import Console
from arcade_cli.toolkit_docs.docs_builder import (
build_example_path,
build_examples,
build_toolkit_mdx,
build_toolkit_mdx_file_path,
)
from arcade_cli.toolkit_docs.utils import (
get_all_enumerations,
get_list_of_tools,
has_wrapper_tools_directory,
print_debug_func,
read_toolkit_metadata,
resolve_api_key,
standardize_dir_path,
write_file,
)
def generate_toolkit_docs(
console: Console,
toolkit_name: str,
toolkit_dir: str,
docs_section: str,
docs_dir: str,
openai_model: str,
openai_api_key: str | None = None,
tool_call_examples: bool = True,
debug: bool = False,
) -> bool:
openai.api_key = resolve_api_key(openai_api_key, "OPENAI_API_KEY")
if not openai.api_key:
console.print(
"❌ Provide --openai-api-key argument or set the OPENAI_API_KEY environment variable",
style="red",
)
return False
print_debug = partial(print_debug_func, debug, console)
docs_dir = standardize_dir_path(docs_dir)
toolkit_dir = standardize_dir_path(toolkit_dir)
is_wrapper_toolkit = has_wrapper_tools_directory(toolkit_dir)
print_debug("Reading server metadata")
pip_package_name = read_toolkit_metadata(toolkit_dir)
print_debug(f"Getting list of tools for {toolkit_name} from the local Python environment")
tools = get_list_of_tools(toolkit_name)
print_debug(f"Found {len(tools)} tools")
print_debug("Getting all enumerations potentially used in tool argument specs")
enums = get_all_enumerations(toolkit_dir)
toolkit_mdx_file_path = build_toolkit_mdx_file_path(docs_section, docs_dir, toolkit_name)
print_debug(f"Building {toolkit_mdx_file_path} file")
toolkit_mdx = build_toolkit_mdx(
toolkit_package_name=toolkit_name,
toolkit_dir=toolkit_dir,
tools=tools,
docs_section=docs_section,
enums=enums,
pip_package_name=pip_package_name,
openai_model=openai_model,
is_wrapper_toolkit=is_wrapper_toolkit,
)
write_file(toolkit_mdx_file_path, toolkit_mdx)
if tool_call_examples:
print_debug("Building tool-call examples in Python and JavaScript")
examples = build_examples(print_debug, tools, openai_model)
for filename, example in examples:
example_path = build_example_path(filename, docs_dir, toolkit_name)
write_file(example_path, example)
print_debug(f"Done generating docs for {toolkit_name}")
return True

603
libs/arcade-cli/arcade_cli/toolkit_docs/docs_builder.py
View file

@ -1,603 +0,0 @@
import json
import os
import pprint
from enum import Enum
from typing import Any, Callable, cast
import openai
from arcade_core import auth as auth_module
from arcade_core.schema import (
ToolAuthRequirement,
ToolDefinition,
ToolInput,
ToolSecretRequirement,
)
from rich.console import Console
from arcade_cli.toolkit_docs.templates import (
ENUM_ITEM,
ENUM_MDX,
ENUM_VALUE,
GENERIC_PROVIDER_CONFIG,
STARTER_TOOL_INFO_CALL,
STARTER_TOOLKIT_HEADER_IMPORT,
TABBED_EXAMPLES_LIST,
TABLE_OF_CONTENTS,
TABLE_OF_CONTENTS_ITEM,
TOOL_CALL_EXAMPLE_JS,
TOOL_CALL_EXAMPLE_PY,
TOOL_PARAMETER,
TOOL_SPEC,
TOOL_SPEC_SECRETS,
TOOLKIT_FOOTER,
TOOLKIT_FOOTER_OAUTH2,
TOOLKIT_HEADER,
TOOLKIT_PAGE,
WELL_KNOWN_PROVIDER_CONFIG,
)
from arcade_cli.toolkit_docs.utils import (
clean_fully_qualified_name,
find_enum_by_options,
find_pyproject_toml,
get_pyproject_description,
get_toolkit_auth_type,
is_well_known_provider,
pascal_to_snake_case,
)
console = Console()
def build_toolkit_mdx_dir_path(
docs_section: str,
docs_root_dir: str,
toolkit_name: str,
ensure_exists: bool = True,
) -> str:
dir_path = os.path.join(
docs_root_dir,
"app",
"en",
"mcp-servers",
docs_section,
f"{toolkit_name.lower().replace('_', '-')}",
)
if ensure_exists:
os.makedirs(dir_path, exist_ok=True)
return dir_path
def build_toolkit_mdx_file_path(docs_section: str, docs_root_dir: str, toolkit_name: str) -> str:
toolkit_dir_path = build_toolkit_mdx_dir_path(docs_section, docs_root_dir, toolkit_name)
return os.path.join(toolkit_dir_path, "page.mdx")
def build_example_path(example_filename: str, docs_root_dir: str, toolkit_name: str) -> str:
return os.path.join(
docs_root_dir,
"public",
"examples",
"integrations",
"mcp-servers",
toolkit_name.lower(),
example_filename,
)
def build_toolkit_mdx(
toolkit_package_name: str,
toolkit_dir: str,
tools: list[ToolDefinition],
docs_section: str,
enums: dict[str, type[Enum]],
pip_package_name: str,
openai_model: str,
toolkit_header_template: str = TOOLKIT_HEADER,
toolkit_page_template: str = TOOLKIT_PAGE,
is_wrapper_toolkit: bool = False,
) -> tuple[str, str]:
sample_tool = tools[0]
toolkit_name = sample_tool.toolkit.name
toolkit_version = sample_tool.toolkit.version
auth_type = get_toolkit_auth_type(sample_tool.requirements)
if is_wrapper_toolkit:
starter_tool_info_import = STARTER_TOOLKIT_HEADER_IMPORT
starter_tool_info_warning = STARTER_TOOL_INFO_CALL.format(toolkit_name=toolkit_name)
else:
starter_tool_info_import = ""
starter_tool_info_warning = ""
try:
pyproject_path = find_pyproject_toml(toolkit_dir)
tool_info_description = get_pyproject_description(pyproject_path)
except ValueError:
tool_info_description = f"Enable Agents to interact with the {toolkit_name} MCP Server"
header = toolkit_header_template.format(
toolkit_title=toolkit_name,
tool_info_description=tool_info_description,
starter_tool_info_import=starter_tool_info_import,
starter_tool_info_warning=starter_tool_info_warning,
description=generate_toolkit_description(
toolkit_name,
[(tool.name, tool.description) for tool in tools],
openai_model,
),
pip_package_name=pip_package_name,
auth_type=auth_type,
version=toolkit_version,
)
table_of_contents = build_table_of_contents(tools)
footer = build_footer(toolkit_name, pip_package_name, sample_tool.requirements.authorization)
referenced_enums, tools_specs = build_tools_specs(
toolkit_package_name, tools, docs_section, enums
)
reference_mdx = build_reference_mdx(toolkit_name, referenced_enums) if referenced_enums else ""
toolkit_mdx = toolkit_page_template.format(
header=header,
table_of_contents=table_of_contents,
tools_specs=tools_specs,
reference_mdx=reference_mdx,
footer=footer,
)
return toolkit_mdx.strip()
def build_reference_mdx(
toolkit_name: str,
referenced_enums: list[tuple[str, type[Enum]]],
enum_item_template: str = ENUM_ITEM,
enum_value_template: str = ENUM_VALUE,
enum_mdx_template: str = ENUM_MDX,
) -> str:
enum_items = ""
enum_names_seen = set()
for enum_name, enum_class in referenced_enums:
if enum_name in enum_names_seen:
continue
enum_names_seen.add(enum_name)
enum_items += enum_item_template.format(
enum_name=enum_name,
enum_values=build_enum_values(
enum_class=enum_class,
enum_value_template=enum_value_template,
),
)
return enum_mdx_template.format(
toolkit_name=toolkit_name,
enum_items=enum_items,
)
def build_enum_values(
enum_class: type[Enum],
enum_value_template: str = ENUM_VALUE,
) -> str:
enum_values = ""
for enum_member in enum_class:
enum_values += (
enum_value_template.format(
enum_option_name=enum_member.name,
enum_option_value=enum_member.value,
)
+ "\n"
)
return enum_values
def build_table_of_contents(
tools: list[ToolDefinition],
table_of_contents_item_template: str = TABLE_OF_CONTENTS_ITEM,
table_of_contents_template: str = TABLE_OF_CONTENTS,
) -> str:
tools_items = ""
for tool in tools:
tools_items += table_of_contents_item_template.format(
tool_fully_qualified_name=clean_fully_qualified_name(tool.fully_qualified_name),
description=tool.description.split("\n")[0],
)
return table_of_contents_template.format(tool_items=tools_items)
def build_footer(
toolkit_name: str,
pip_package_name: str,
authorization: ToolAuthRequirement | None,
footer_template: str = TOOLKIT_FOOTER,
oauth2_footer_template: str = TOOLKIT_FOOTER_OAUTH2,
well_known_provider_config_template: str = WELL_KNOWN_PROVIDER_CONFIG,
generic_provider_config_template: str = GENERIC_PROVIDER_CONFIG,
) -> str:
if authorization and authorization.provider_type == "oauth2" and authorization.provider_id:
is_well_known = is_well_known_provider(
provider_id=authorization.provider_id,
auth_module=auth_module,
)
config_template = (
well_known_provider_config_template
if is_well_known
else generic_provider_config_template
)
provider_configuration = config_template.format(
toolkit_name=toolkit_name,
provider_id=authorization.provider_id,
provider_name=authorization.provider_id.capitalize(),
)
return oauth2_footer_template.format(
pip_package_name=pip_package_name,
provider_configuration=provider_configuration,
)
return footer_template.format(toolkit_name=toolkit_name, pip_package_name=pip_package_name)
def build_tools_specs(
toolkit_name: str,
tools: list[ToolDefinition],
docs_section: str,
enums: dict[str, type[Enum]],
tool_spec_template: str = TOOL_SPEC,
tool_parameter_template: str = TOOL_PARAMETER,
tool_spec_secrets_template: str = TOOL_SPEC_SECRETS,
) -> tuple[list[tuple[str, type[Enum]]], str]:
tools_specs = ""
referenced_enums = []
for tool in tools:
tool_referenced_enums, tool_spec = build_tool_spec(
toolkit_name=toolkit_name,
tool=tool,
docs_section=docs_section,
enums=enums,
tool_spec_template=tool_spec_template,
tool_parameter_template=tool_parameter_template,
tool_spec_secrets_template=tool_spec_secrets_template,
)
tools_specs += tool_spec
referenced_enums.extend(tool_referenced_enums)
return referenced_enums, tools_specs
def build_tool_spec(
toolkit_name: str,
tool: ToolDefinition,
docs_section: str,
enums: dict[str, type[Enum]],
tool_spec_template: str = TOOL_SPEC,
tool_parameter_template: str = TOOL_PARAMETER,
tool_spec_secrets_template: str = TOOL_SPEC_SECRETS,
) -> tuple[list[tuple[str, type[Enum]]], str]:
tabbed_examples_list = TABBED_EXAMPLES_LIST.format(
toolkit_name=toolkit_name.lower(),
tool_name=pascal_to_snake_case(tool.name),
)
referenced_enums, parameters = build_tool_parameters(
tool_input=tool.input,
docs_section=docs_section,
toolkit_name=tool.toolkit.name.lower(),
enums=enums,
tool_parameter_template=tool_parameter_template,
)
if not parameters:
parameters = "This tool does not take any parameters."
secrets = (
build_tool_secrets(
secrets=tool.requirements.secrets,
template=tool_spec_secrets_template,
)
if tool.requirements.secrets
else ""
)
return referenced_enums, tool_spec_template.format(
tool_fully_qualified_name=clean_fully_qualified_name(tool.fully_qualified_name),
tabbed_examples_list=tabbed_examples_list,
description=tool.description.split("\n")[0],
parameters=parameters,
secrets=secrets,
)
def build_tool_secrets(
secrets: list[ToolSecretRequirement],
template: str = TOOL_SPEC_SECRETS,
) -> str:
if not secrets:
return ""
secret_keys_str = "`, `".join([secret.key for secret in secrets])
return template.format(secrets=f"`{secret_keys_str}`")
def build_tool_parameters(
tool_input: ToolInput,
docs_section: str,
toolkit_name: str,
enums: dict[str, type[Enum]],
tool_parameter_template: str = TOOL_PARAMETER,
) -> tuple[list[tuple[str, type[Enum]]], str]:
referenced_enums = []
parameters = ""
for parameter in tool_input.parameters:
schema = parameter.value_schema
if schema.enum:
enum_name, enum_class = find_enum_by_options(enums, schema.enum)
referenced_enums.append((enum_name, enum_class))
param_definition = f"`Enum` [{enum_name}](/mcp-servers/{docs_section}/{toolkit_name}/reference#{enum_name})"
else:
if schema.inner_val_type:
param_definition = f"`{schema.val_type}[{schema.inner_val_type}]`"
else:
param_definition = f"`{schema.val_type}`"
if parameter.required:
param_definition += ", required"
else:
param_definition += ", optional"
parameters += (
tool_parameter_template.format(
param_name=parameter.name,
definition=param_definition,
description=parameter.description,
)
+ "\n"
)
return referenced_enums, parameters
def build_examples(
print_debug: Callable,
tools: list[ToolDefinition],
openai_model: str,
) -> list[tuple[str, str]]:
examples = []
for tool in tools:
print_debug(f"Generating tool-call examples for {tool.name}")
interface_signature = build_tool_interface_signature(tool)
input_map = generate_tool_input_map(interface_signature, openai_model)
fully_qualified_name = tool.fully_qualified_name.split("@")[0]
py_file_name = f"{pascal_to_snake_case(tool.name)}_example_call_tool.py"
examples.append((
py_file_name,
build_python_example(fully_qualified_name, input_map),
))
js_file_name = f"{pascal_to_snake_case(tool.name)}_example_call_tool.js"
examples.append((
js_file_name,
build_javascript_example(fully_qualified_name, input_map),
))
return examples
def build_python_example(
tool_fully_qualified_name: str,
input_map: dict[str, Any],
template: str = TOOL_CALL_EXAMPLE_PY,
) -> str:
input_map_str = pprint.pformat(
input_map,
indent=4,
width=100,
compact=False,
sort_dicts=False,
)
input_map_str = "{\n " + input_map_str.lstrip("{ ").rstrip("}") + "\n}" # noqa: B005
return template.format(
tool_fully_qualified_name=tool_fully_qualified_name,
input_map=input_map_str,
)
def build_javascript_example(
tool_fully_qualified_name: str,
input_map: dict,
template: str = TOOL_CALL_EXAMPLE_JS,
) -> str:
return template.format(
tool_fully_qualified_name=tool_fully_qualified_name,
input_map=json.dumps(input_map, indent=2, ensure_ascii=False),
)
def generate_toolkit_description(
toolkit_name: str,
tools: list[tuple[str, str]],
openai_model: str,
) -> str:
messages = [
{
"role": "system",
"content": (
"You are a helpful assistant. "
"When given an MCP Server name and a list of tools, you will generate a "
"short, yet descriptive of the MCP Server and the main actions a user "
"or LLM can perform with it.\n\n"
"As an example, here is the Asana MCP Server description:\n\n"
"The Arcade Asana MCP Server provides a pre-built set of tools for "
"interacting with Asana. These tools make it easy to build agents "
"and AI apps that can:\n\n"
"- Manage teams, projects, and workspaces.\n"
"- Create, update, and search for tasks.\n"
"- Retrieve data about tasks, projects, workspaces, users, etc.\n"
"- Manage task attachments.\n\n"
"And here is a JSON string with the list of tools in the Asana MCP Server:\n\n"
"```json\n\n"
'[["AttachFileToTask", "Attaches a file to an Asana task\n\nProvide exactly '
"one of file_content_str, file_content_base64, or file_content_url, never "
"more\nthan one.\n\n- Use file_content_str for text files (will be encoded "
"using file_encoding)\n- Use file_content_base64 for binary files like images, "
'PDFs, etc.\n- Use file_content_url if the file is hosted on an external URL"], '
'["CreateTag", "Create a tag in Asana"], ["CreateTask", "Creates a task in '
"Asana\n\nThe task must be associated to at least one of the following: "
"parent_task_id, project, or\nworkspace_id. If none of these are provided and "
"the account has only one workspace, the task\nwill be associated to that "
"workspace. If the account has multiple workspaces, an error will\nbe raised "
'with a list of available workspaces."], ["GetProjectById", "Get an Asana '
'project by its ID"], ["GetSubtasksFromATask", "Get the subtasks of a task"], '
'["GetTagById", "Get an Asana tag by its ID"], ["GetTaskById", "Get a task by '
'its ID"], ["GetTasksWithoutId", "Search for tasks"], ["GetTeamById", "Get an '
'Asana team by its ID"], ["GetUserById", "Get a user by ID"], ["GetWorkspaceById", '
'"Get an Asana workspace by its ID"], ["ListProjects", "List projects in Asana"], '
'["ListTags", "List tags in an Asana workspace"], ["ListTeams", "List teams in '
'an Asana workspace"], ["ListTeamsTheCurrentUserIsAMemberOf", "List teams in '
'Asana that the current user is a member of"], ["ListUsers", "List users in '
'Asana"], ["ListWorkspaces", "List workspaces in Asana that are visible to the '
'authenticated user"], ["MarkTaskAsCompleted", "Mark a task in Asana as '
'completed"], ["UpdateTask", "Updates a task in Asana"]]\n\n```\n\n'
"Keep the description concise and to the point. The user will provide you with "
"the MCP Server name and the list of tools. Generate the description according to "
"the instructions above."
),
},
{
"role": "user",
"content": (
f"The MCP Server name is {toolkit_name} and the list of tools is:\n\n"
"```json\n\n"
f"{json.dumps(tools, ensure_ascii=False)}\n\n"
"```\n\n"
"Please generate a description for the MCP Server."
),
},
]
return request_openai_generation(model=openai_model, max_tokens=512, messages=messages)
def generate_tool_input_map(
interface_signature: dict[str, Any],
openai_model: str,
retries: int = 0,
max_retries: int = 3,
) -> dict[str, Any]:
messages = [
{
"role": "system",
"content": (
"You are a helpful assistant expert in generating data for documenting "
"sample scripts to calling tools. A tool is a function that is used in "
"context of LLM tool-calling / function-calling.\n\n"
"When given a tool signature with typed arguments, "
"you must return exactly one JSON object (no markdown, no extra text) "
"where each key is an argument name, and each value is a sample value "
"for that argument that would make sense in a sample script to showcase "
"human software engineers how the tool may be called. Generate the "
"argument sample value based on its name and description\n\n"
"Not every single argument must always be present in the input map. "
"In some cases, the tool may require only one of two arguments to be "
"provided, for example. In such cases, an indication will be present "
"either/or in the tool description or the argument description. "
"Always follow such instructions when present in the tool interface.\n\n"
"Keep argument values as short as possible. Values don't have to always "
"be valid. For instance, for file content base64-encoded arguments, "
"you can use a short text or a placeholder like `[file_content]`, it is "
"not necessary that the value is a valid base64-encoded string.\n\n"
"Remember that you MUST RESPOND ONLY WITH A VALID JSON STRING, NO ADDED "
"TEXT. Your response will be json.load'ed, so it must be a valid JSON "
"string."
),
},
{
"role": "user",
"content": (
"Here is a tool interface:\n\n"
f"{json.dumps(interface_signature, ensure_ascii=False)}\n\n"
"Please provide a sample input map as a JSON object."
),
},
]
text = request_openai_generation(model=openai_model, max_tokens=512, messages=messages)
try:
return cast(dict[str, Any], json.loads(text))
except (json.JSONDecodeError, TypeError):
if retries < max_retries:
return generate_tool_input_map(
interface_signature=interface_signature,
openai_model=openai_model,
retries=retries + 1,
max_retries=max_retries,
)
tool_name = interface_signature["tool_name"]
console.print(
f"Attention: {openai_model} failed to generate a valid inputs JSON for the tool '{tool_name}'. "
"Please check the Python & Javascript example scripts generated and enter a sample input manually.",
style="red",
)
return {}
def build_tool_interface_signature(tool: ToolDefinition) -> dict[str, Any]:
args = []
for arg in tool.input.parameters:
data: dict[str, Any] = {
"arg_name": arg.name,
"arg_description": arg.description,
"is_arg_required": arg.required,
"arg_type": arg.value_schema.val_type,
}
if arg.value_schema.enum:
data["enum"] = {
"accepted_values": arg.value_schema.enum,
}
args.append(data)
return {
"tool_name": tool.name,
"tool_description": tool.description,
"tool_args": args,
}
def request_openai_generation(
model: str,
max_tokens: int,
messages: list[dict[str, Any]],
) -> str:
if model.startswith("gpt-5"):
response = openai.responses.create(
model=model,
input=messages,
max_output_tokens=max_tokens,
reasoning={
"effort": "minimal",
},
text={
"verbosity": "low",
},
)
response_str = cast(str, response.output_text)
elif model.startswith("gpt-4o"):
response = openai.chat.completions.create(
model=model,
messages=messages,
temperature=0.0,
max_completion_tokens=max_tokens,
stop=["\n\n"],
)
response_str = cast(str, response.choices[0].message.content)
else:
raise ValueError(
f"Unsupported OpenAI model: {model}. Choose a model from the 'gpt-4o' or 'gpt-5' series."
)
return response_str.strip()

168
libs/arcade-cli/arcade_cli/toolkit_docs/templates.py
View file

@ -1,168 +0,0 @@
TOOLKIT_PAGE = """{header}
{table_of_contents}
{tools_specs}
{reference_mdx}
{footer}
"""
STARTER_TOOLKIT_HEADER_IMPORT = 'import StarterToolInfo from "@/app/_components/starter-tool-info";'
STARTER_TOOL_INFO_CALL = '<StarterToolInfo toolkitName="{toolkit_name}" />'
TOOLKIT_HEADER = """# {toolkit_title}
{starter_tool_info_import}
import ToolInfo from "@/app/_components/tool-info";
import Badges from "@/app/_components/badges";
import TabbedCodeBlock from "@/app/_components/tabbed-code-block";
import TableOfContents from "@/app/_components/table-of-contents";
import ToolFooter from "@/app/_components/tool-footer";
import {{ Callout }} from "nextra/components";
<ToolInfo
description="{tool_info_description}"
author="Arcade"
{auth_type}
versions={{["{version}"]}}
/>
<Badges repo="arcadeai/{pip_package_name}" />
{starter_tool_info_warning}
{description}"""
TABLE_OF_CONTENTS = """## Available Tools
<TableOfContents
headers={{["Tool Name", "Description"]}}
data={{
[{tool_items}
]
}}
/>
<Callout>
If you need to perform an action that's not listed here, you can [get in touch
with us](mailto:contact@arcade.dev) to request a new tool, or [create your
own tools](/home/build-tools/create-a-mcp-server).
</Callout>"""
TABLE_OF_CONTENTS_ITEM = '\n ["{tool_fully_qualified_name}", "{description}"],'
TOOL_SPEC = """## {tool_fully_qualified_name}
<br />
{tabbed_examples_list}
{description}
**Parameters**
{parameters}
{secrets}
"""
TOOL_SPEC_SECRETS = """**Secrets**
This tool requires the following secrets: {secrets} (learn how to [configure secrets](/home/build-tools/create-a-tool-with-secrets#set-the-secret-in-the-arcade-dashboard))
"""
TABBED_EXAMPLES_LIST = """<TabbedCodeBlock
tabs={{[
{{
label: "Call the Tool Directly",
content: {{
Python: ["/examples/integrations/mcp-servers/{toolkit_name}/{tool_name}_example_call_tool.py"],
JavaScript: ["/examples/integrations/mcp-servers/{toolkit_name}/{tool_name}_example_call_tool.js"],
}},
}},
]}}
/>"""
TOOL_PARAMETER = "- **{param_name}** ({definition}) {description}"
TOOLKIT_FOOTER = """<ToolFooter pipPackageName="{pip_package_name}" />"""
TOOLKIT_FOOTER_OAUTH2 = """## Auth
{provider_configuration}
<ToolFooter pipPackageName="{pip_package_name}" />
"""
WELL_KNOWN_PROVIDER_CONFIG = "The Arcade {toolkit_name} MCP Server uses the [{provider_name} auth provider](/home/auth-providers/{provider_id}) to connect to users' {toolkit_name} accounts. Please refer to the [{provider_name} auth provider](/home/auth-providers/{provider_id}) documentation to learn how to configure auth."
GENERIC_PROVIDER_CONFIG = "The {toolkit_name} MCP Server uses the Auth Provider with id `{provider_id}` to connect to users' {toolkit_name} accounts. In order to use the MCP Server, you will need to configure the `{provider_id}` auth provider."
TOOL_CALL_EXAMPLE_JS = """import {{ Arcade }} from "@arcadeai/arcadejs";
const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
const USER_ID = "{{arcade_user_id}}";
const TOOL_NAME = "{tool_fully_qualified_name}";
// Start the authorization process
const authResponse = await client.tools.authorize({{tool_name: TOOL_NAME}});
if (authResponse.status !== "completed") {{
console.log(`Click this link to authorize: ${{authResponse.url}}`);
}}
// Wait for the authorization to complete
await client.auth.waitForCompletion(authResponse);
const toolInput = {input_map};
const response = await client.tools.execute({{
tool_name: TOOL_NAME,
input: toolInput,
user_id: USER_ID,
}});
console.log(JSON.stringify(response.output.value, null, 2));
"""
TOOL_CALL_EXAMPLE_PY = """import json
from arcadepy import Arcade
client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable
USER_ID = "{{arcade_user_id}}"
TOOL_NAME = "{tool_fully_qualified_name}"
auth_response = client.tools.authorize(
tool_name=TOOL_NAME,
user_id=USER_ID,
)
if auth_response.status != "completed":
print(f"Click this link to authorize: {{auth_response.url}}")
# Wait for the authorization to complete
client.auth.wait_for_completion(auth_response)
tool_input = {input_map}
response = client.tools.execute(
tool_name=TOOL_NAME,
input=tool_input,
user_id=USER_ID,
)
print(json.dumps(response.output.value, indent=2))
"""
ENUM_MDX = """## Reference
Below is a reference of enumerations used by some of the tools in the {toolkit_name} MCP Server:
{enum_items}
"""
ENUM_ITEM = """## {enum_name}
{enum_values}
"""
ENUM_VALUE = "- **{enum_option_name}**: `{enum_option_value}`"

220
libs/arcade-cli/arcade_cli/toolkit_docs/utils.py
View file

@ -1,220 +0,0 @@
import importlib
import inspect
import os
import re
import sys
from enum import Enum
from pathlib import Path
from types import ModuleType
if sys.version_info >= (3, 11):
import tomllib
else:
tomllib = None
from arcade_core.auth import AuthProviderType
from arcade_core.catalog import ToolCatalog
from arcade_core.schema import ToolDefinition, ToolRequirements
from rich.console import Console
from arcade_cli.utils import discover_toolkits
def print_debug_func(debug: bool, console: Console, message: str, style: str = "dim") -> None:
if not debug:
return
console.print(message, style=style)
def standardize_dir_path(dir_path: str) -> str:
dir_path = dir_path.rstrip("/") + "/"
return os.path.expanduser(dir_path)
def resolve_api_key(cli_input_value: str | None, env_var_name: str) -> str | None:
if cli_input_value:
return cli_input_value
elif os.getenv(env_var_name):
return os.getenv(env_var_name)
else:
return None
def write_file(path: str, content: str) -> None:
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "w") as f:
f.write(content)
def read_toolkit_metadata(toolkit_dir: str) -> str:
pyproject_path = os.path.join(toolkit_dir, "pyproject.toml")
if tomllib is not None:
with open(pyproject_path, "rb") as f:
data = tomllib.load(f)
if "project" in data and "name" in data["project"]:
return data["project"]["name"]
else:
# Fallback to regex for Python < 3.11
with open(pyproject_path) as f:
content = f.read()
project_section_match = re.search(r"\[project\](.*?)(?=\n\[|$)", content, re.DOTALL)
if project_section_match:
project_content = project_section_match.group(1)
name_match = re.search(r'name\s*=\s*["\']([^"\']+)["\']', project_content)
if name_match:
return name_match.group(1).strip()
raise ValueError(f"Could not find package name in '{pyproject_path}'")
def pascal_to_snake_case(text: str) -> str:
return re.sub(r"(?<!^)(?=[A-Z])", "_", text).lower()
def get_list_of_tools(toolkit_name: str) -> list[ToolDefinition]:
tools = []
toolkits = discover_toolkits()
for toolkit in toolkits:
if toolkit.name.casefold() == toolkit_name.casefold():
for module_name, module_tools in toolkit.tools.items():
module = importlib.import_module(module_name)
for tool_name in module_tools:
tool_func = getattr(module, tool_name)
tool = ToolCatalog.create_tool_definition(
tool_func, toolkit.name, toolkit.version, toolkit.description
)
tools.append(tool)
if not tools:
raise ValueError(
f"Tools not found for the toolkit '{toolkit_name}'. Make sure to have the toolkit "
"installed in your current Python environment."
)
return tools
def get_all_enumerations(toolkit_root_dir: str) -> dict[str, type[Enum]]:
enums = {}
toolkit_path = Path(toolkit_root_dir)
for py_file in toolkit_path.rglob("*.py"):
if py_file.name == "__init__.py":
continue
if ".venv" in py_file.parts or "venv" in py_file.parts:
continue
module_name = py_file.stem
spec = importlib.util.spec_from_file_location(module_name, py_file)
if spec is None or spec.loader is None:
continue
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
for name, obj in inspect.getmembers(module):
if (
name not in enums
and inspect.isclass(obj)
and issubclass(obj, Enum)
and obj is not Enum
):
enums[name] = obj
return enums
def get_toolkit_auth_type(tool_req: ToolRequirements | None) -> str:
if tool_req.authorization:
if tool_req.authorization.provider_type == AuthProviderType.oauth2.value:
return 'authType="OAuth2"'
else:
return f'authType="{tool_req.authorization.provider_type}"'
elif tool_req.secrets:
return 'authType="API Key"'
return 'authType="None"'
def find_enum_by_options(
enums: dict[str, type[Enum]], options: list[str]
) -> tuple[str, type[Enum]]:
options_set = set(options)
for enum_name, enum_class in enums.items():
enum_member_values = [member.value for member in enum_class]
if set(enum_member_values) == options_set:
return enum_name, enum_class
raise ValueError(f"No enum found for options: {options_set}")
def is_well_known_provider(
provider_id: str | None,
auth_module: ModuleType,
) -> bool:
if provider_id is None:
return False
for _, obj in inspect.getmembers(auth_module, inspect.isclass):
if not issubclass(obj, auth_module.OAuth2) or obj is auth_module.OAuth2:
continue
try:
instance = obj()
except AttributeError:
continue
provider_id_matches = (
hasattr(instance, "provider_id") and instance.provider_id == provider_id
)
if provider_id_matches:
return True
return False
def clean_fully_qualified_name(fully_qualified_name: str) -> str:
return fully_qualified_name.split("@")[0]
def has_wrapper_tools_directory(toolkit_package_path: str) -> bool:
has_dir = os.path.exists(os.path.join(toolkit_package_path, "wrapper_tools"))
if has_dir:
return True
# Check one level deep
for dir_name in os.listdir(toolkit_package_path):
if os.path.exists(os.path.join(toolkit_package_path, dir_name, "wrapper_tools")):
return True
return False
def find_pyproject_toml(toolkit_package_path: str) -> str:
for root, _, files in os.walk(toolkit_package_path):
for file in files:
if file == "pyproject.toml":
return os.path.join(root, file)
raise ValueError(f"No pyproject.toml found in {toolkit_package_path}")
def get_pyproject_description(pyproject_path: str) -> str:
if tomllib is not None:
with open(pyproject_path, "rb") as f:
data = tomllib.load(f)
if "project" in data and "description" in data["project"]:
return data["project"]["description"]
else:
# Fallback to regex for Python < 3.11
with open(pyproject_path) as f:
content = f.read()
project_section_match = re.search(r"\[project\](.*?)(?=\n\[|$)", content, re.DOTALL)
if project_section_match:
project_content = project_section_match.group(1)
description_match = re.search(
r'description\s*=\s*["\']([^"\']+)["\']', project_content
)
if description_match:
return description_match.group(1).strip()
raise ValueError(f"Could not find description in '{pyproject_path}'")

57
libs/tests/cli/toolkit_docs/test_docs_builder.py
View file

@ -1,57 +0,0 @@
import json
from arcade_cli.toolkit_docs.docs_builder import build_javascript_example, build_python_example
from arcade_cli.toolkit_docs.templates import TOOL_CALL_EXAMPLE_JS, TOOL_CALL_EXAMPLE_PY
def test_build_javascript_example():
tool_fully_qualified_name = "Toolkit.ToolName"
input_map = {
"str_arg": "str_value",
"fake_bool_value": "true",
"fake_bool_phrase": "this is not a true boolean",
"int_arg": 123,
"bool_arg": True,
"list_arg": ["item1", "item2"],
"dict_arg": {"key1": "value1", "key2": "value2"},
"list_of_bool": [True, False],
}
response = build_javascript_example(tool_fully_qualified_name, input_map, TOOL_CALL_EXAMPLE_JS)
assert response == TOOL_CALL_EXAMPLE_JS.format(
tool_fully_qualified_name=tool_fully_qualified_name,
input_map=json.dumps(input_map, indent=2, ensure_ascii=False),
)
def test_build_python_example():
tool_fully_qualified_name = "Toolkit.ToolName"
input_map = {
"str_arg": "str_value",
"fake_bool_value": "true",
"fake_bool_phrase": "this is not a true boolean",
"int_arg": 123,
"bool_arg": True,
"list_arg": ["item1", "item2"],
"dict_arg": {"key1": "value1", "key2": "value2"},
"list_of_bool": [True, False],
}
input_map_str = """{
'str_arg': 'str_value',
'fake_bool_value': 'true',
'fake_bool_phrase': 'this is not a true boolean',
'int_arg': 123,
'bool_arg': True,
'list_arg': ['item1', 'item2'],
'dict_arg': {'key1': 'value1', 'key2': 'value2'},
'list_of_bool': [True, False]
}"""
response = build_python_example(tool_fully_qualified_name, input_map, TOOL_CALL_EXAMPLE_PY)
assert response == TOOL_CALL_EXAMPLE_PY.format(
tool_fully_qualified_name=tool_fully_qualified_name,
input_map=input_map_str,
)

175
libs/tests/cli/toolkit_docs/test_docs_builder_utils.py
View file

@ -1,175 +0,0 @@
from types import ModuleType
from unittest.mock import MagicMock, patch
import pytest
from arcade_cli.toolkit_docs.utils import (
clean_fully_qualified_name,
get_toolkit_auth_type,
is_well_known_provider,
pascal_to_snake_case,
read_toolkit_metadata,
)
from arcade_core.auth import Asana, AuthProviderType, Google, OAuth2, Slack
from arcade_core.schema import ToolAuthRequirement
@patch("arcade_cli.toolkit_docs.utils.open")
@patch("arcade_cli.toolkit_docs.utils.tomllib")
def test_read_toolkit_metadata(mock_tomllib, mock_open):
from unittest.mock import MagicMock, mock_open as mock_open_func
sample_pyproject_toml = """
[build-system]
requires = [ "hatchling",]
build-backend = "hatchling.build"
[project]
name = "arcade_jira"
version = "0.1.2"
description = "Arcade.dev LLM tools for interacting with Atlassian Jira"
requires-python = ">=3.10"
dependencies = [
"arcade-tdk>=2.0.0,<3.0.0",
"httpx>=0.27.2,<1.0.0",
]
[[project.authors]]
name = "Arcade"
email = "dev@arcade.dev"
[project.optional-dependencies]
dev = [
"arcade-mcp[evals]>=2.0.0,<3.0.0",
"arcade-serve>=2.0.0,<3.0.0",
"pytest>=8.3.0,<8.4.0",
"pytest-cov>=4.0.0,<4.1.0",
"pytest-asyncio>=0.24.0,<0.25.0",
"pytest-mock>=3.11.1,<3.12.0",
"mypy>=1.5.1,<1.6.0",
"pre-commit>=3.4.0,<3.5.0",
"tox>=4.11.1,<4.12.0",
"ruff>=0.7.4,<0.8.0",
]
# Use local path sources for arcade libs when working locally
[tool.uv.sources]
arcade-mcp = {path = "../../", editable = true}
arcade-tdk = { path = "../../libs/arcade-tdk/", editable = true }
arcade-serve = { path = "../../libs/arcade-serve/", editable = true }
[tool.mypy]
files = [ "arcade_jira/**/*.py",]
python_version = "3.10"
disallow_untyped_defs = "True"
disallow_any_unimported = "True"
no_implicit_optional = "True"
check_untyped_defs = "True"
warn_return_any = "True"
warn_unused_ignores = "True"
show_error_codes = "True"
ignore_missing_imports = "True"
[tool.pytest.ini_options]
testpaths = [ "tests",]
[tool.coverage.report]
skip_empty = true
[tool.hatch.build.targets.wheel]
packages = [ "arcade_jira",]
"""
# Setup mock to handle both binary and text mode
def open_side_effect(path, mode="r"):
if mode == "rb":
return mock_open_func(read_data=sample_pyproject_toml.encode()).return_value
else:
return mock_open_func(read_data=sample_pyproject_toml).return_value
mock_open.side_effect = open_side_effect
mock_tomllib.load.return_value = {"project": {"name": "arcade_jira"}}
assert read_toolkit_metadata("path/to/toolkits/jira") == "arcade_jira"
@patch("arcade_cli.toolkit_docs.utils.open")
@patch("arcade_cli.toolkit_docs.utils.tomllib")
def test_read_toolkit_metadata_missing_project_name(mock_tomllib, mock_open):
from unittest.mock import mock_open as mock_open_func
sample_pyproject_toml = """
[build-system]
requires = [ "hatchling",]
build-backend = "hatchling.build"
[project]
version = "0.1.2"
description = "Arcade.dev LLM tools for interacting with Atlassian Jira"
requires-python = ">=3.10"
dependencies = [
"arcade-tdk>=2.0.0,<3.0.0",
"httpx>=0.27.2,<1.0.0",
]
[[project.authors]]
name = "Arcade"
email = "dev@arcade.dev"
"""
# Setup mock to handle both binary and text mode
def open_side_effect(path, mode="r"):
if mode == "rb":
return mock_open_func(read_data=sample_pyproject_toml.encode()).return_value
else:
return mock_open_func(read_data=sample_pyproject_toml).return_value
mock_open.side_effect = open_side_effect
mock_tomllib.load.return_value = {"project": {}} # Missing "name"
with pytest.raises(ValueError):
read_toolkit_metadata("path/to/toolkits/jira")
def test_pascal_to_snake_case():
assert pascal_to_snake_case("PascalCase") == "pascal_case"
assert pascal_to_snake_case("PascalCase_abc") == "pascal_case_abc"
def test_get_toolkit_auth_type_none():
from arcade_core.schema import ToolRequirements
tool_req = ToolRequirements()
assert get_toolkit_auth_type(tool_req=tool_req) == 'authType="None"'
def test_get_toolkit_auth_type_with_provider_type():
from arcade_core.schema import ToolRequirements, ToolSecretRequirement
tool_req = ToolRequirements(authorization=ToolAuthRequirement(provider_type=AuthProviderType.oauth2.value))
assert get_toolkit_auth_type(tool_req=tool_req) == 'authType="OAuth2"'
tool_req = ToolRequirements(authorization=ToolAuthRequirement(provider_type="another_type"))
assert get_toolkit_auth_type(tool_req=tool_req) == 'authType="another_type"'
tool_req = ToolRequirements(secrets=[ToolSecretRequirement(key="API_KEY")])
assert get_toolkit_auth_type(tool_req=tool_req) == 'authType="API Key"'
def test_is_well_known_provider_none():
assert not is_well_known_provider(provider_id=None, auth_module=MagicMock(spec=ModuleType))
def test_is_well_known_provider_matching_provider_id():
mock_auth_module = MagicMock(spec=ModuleType)
mock_auth_module.OAuth2 = OAuth2
mock_auth_module.Google = Google
mock_auth_module.Slack = Slack
assert is_well_known_provider(provider_id=Google().provider_id, auth_module=mock_auth_module)
assert is_well_known_provider(provider_id=Slack().provider_id, auth_module=mock_auth_module)
assert not is_well_known_provider(provider_id=Asana().provider_id, auth_module=mock_auth_module)
assert not is_well_known_provider(provider_id="another_provider", auth_module=mock_auth_module)
def test_clean_fully_qualified_name():
assert clean_fully_qualified_name("Outlook.ListEmails") == "Outlook.ListEmails"
assert clean_fully_qualified_name("Outlook.ListEmails@1.0.0") == "Outlook.ListEmails"