From afbc3808a428132620d91f9a3517b2cb29e41852 Mon Sep 17 00:00:00 2001 From: Eric Gustin Date: Wed, 29 Oct 2025 18:39:38 -0700 Subject: [PATCH] Update docs --- .../call-tools-from-mcp-clients/page.mdx | 16 ++++----- .../build-tools/create-a-mcp-server/page.mdx | 16 +++++++-- .../organize-mcp-server-tools/page.mdx | 34 ++++++++++++------- app/en/home/build-tools/tool-context/page.mdx | 11 +++--- .../custom-mcp-server-quickstart/page.mdx | 20 ++++++++--- app/en/home/deployment/on-prem-mcp/page.mdx | 4 +-- app/en/references/mcp/python/sharing/page.mdx | 4 +-- .../references/mcp/python/transports/page.mdx | 2 +- 8 files changed, 69 insertions(+), 38 deletions(-) diff --git a/app/en/home/build-tools/call-tools-from-mcp-clients/page.mdx b/app/en/home/build-tools/call-tools-from-mcp-clients/page.mdx index a63c1de0e..fda7a8c52 100644 --- a/app/en/home/build-tools/call-tools-from-mcp-clients/page.mdx +++ b/app/en/home/build-tools/call-tools-from-mcp-clients/page.mdx @@ -33,7 +33,7 @@ Configure your MCP clients to call tools from your MCP server. ## Using the `arcade configure` command -For popular MCP clients, you can use the `arcade configure` command to configure your MCP client to call your MCP server. This will automatically add the MCP server to your client's configuration file. By default, it will use the stdio transport. +For popular MCP clients, you can use the `arcade configure` command to configure your MCP client to call your MCP server. This will automatically add the MCP server to your client's configuration file. By default, it will use the stdio transport. You must run this command from the directory of your entrypoint file. Note that the `--entrypoint` determines only the filename of the entrypoint @@ -99,7 +99,7 @@ If you are using the stdio transport, `arcade configure` will assume the entrypo When using the stdio transport, `arcade configure` will automatically load the - secrets from the `.env` file in the root of your project into the appropriate + secrets from the `.env` file at the directory of your entrypoint file into the appropriate configuration file for your MCP client. @@ -170,14 +170,14 @@ If you are using the streamable HTTP transport, `arcade configure` will assume t -Claude Desktop does not currently support the http transport. +Claude Desktop does not currently support the http transport via JSON configuration files. ### Other configuration options -If you have modified the default configuration of your MCP client, you can pass the `--config` (or `-c`) option to `arcade configure` to use your custom configuration file: +If you have modified the default configuration of your MCP client, or want to use a profile/workspace specific configuration file, then you can pass the `--config` (or `-c`) option to `arcade configure` to use your custom configuration file: @@ -49,7 +49,7 @@ In your terminal, run the following command to scaffold a new MCP Server called ```bash arcade new my_server -cd my_server +cd my_server/src/my_server ``` @@ -57,7 +57,17 @@ cd my_server do so by running `arcade login` in your terminal. -This generates a complete project with: +This generates a Python module with the following structure: + +```bash +my_server/ +├── src/ +│ └── my_server/ +│ ├── __init__.py +│ ├── .env.example +│ └── server.py +└── pyproject.toml +``` - **server.py** Main server file with MCPApp and example tools - **pyproject.toml** Dependencies and project configuration diff --git a/app/en/home/build-tools/organize-mcp-server-tools/page.mdx b/app/en/home/build-tools/organize-mcp-server-tools/page.mdx index b6e9025f7..c570c2ab2 100644 --- a/app/en/home/build-tools/organize-mcp-server-tools/page.mdx +++ b/app/en/home/build-tools/organize-mcp-server-tools/page.mdx @@ -33,18 +33,21 @@ Learn best practices for organizing your MCP server and tools, how to import too ## Project Structure -We recommend keeping your MCP server file at the root of your project and keeping your tools in separate files in a `tools` directory like so: +We recommend keeping your MCP server file and tools in separate files in a `tools` directory like so: ```bash my_server/ - ├── .env - ├── server.py # Main MCPApp - ├── tools/ - │ ├── __init__.py - │ ├── math_tools.py # @tool decorated functions - │ └── text_tools.py # @tool decorated functions - ├── pyproject.toml - └── README.md + ├── src/ + │ └── my_server/ + │ ├── .env + │ ├── server.py # Entrypoint file with your MCPApp + │ ├── tools/ + │ │ ├── __init__.py + │ │ ├── math_tools.py # @tool decorated functions + │ │ └── text_tools.py # @tool decorated functions + │ ├── pyproject.toml + │ └── README.md + └── pyproject.toml ``` ## Defining tools @@ -74,23 +77,30 @@ from tools.math_tools import add, multiply from tools.text_tools import capitalize_string, word_count ``` -You could also import from Arcade PyPI packages: +You could also import specific tools from Arcade PyPI packages: ```python filename="server.py" from arcade_gmail.tools import list_emails ``` -Add imported tools explicitly to the MCP server app object like this: +You can also import whole modules that contain tools like this: + +```python filename="server.py" +import arcade_reddit +``` + +Add imported tools explicitly to the `MCPApp` instance like this: ```python filename="server.py" app.add_tool(add) app.add_tool(list_emails) +app.add_tools_from_module(arcade_reddit) ``` ## Key takeaways - Keep your MCP server file clean and readable by defining tools in separate files -- Store your tools in a `tools` directory in your project root alongside your MCP server file +- Store your tools in a `tools` directory in your project alongside your MCP server file - You can import tools from other Arcade packages and your own files - Add imported tools explicitly to the MCP server app object diff --git a/app/en/home/build-tools/tool-context/page.mdx b/app/en/home/build-tools/tool-context/page.mdx index 198f92657..734a4c384 100644 --- a/app/en/home/build-tools/tool-context/page.mdx +++ b/app/en/home/build-tools/tool-context/page.mdx @@ -18,15 +18,15 @@ import { Callout, Tabs } from "nextra/components"; Some authorization providers may also include additional structured user -information in the `ToolContext`. +information in the `Context`. You can access this information via `context.authorization.user_info`. ## How `Context` Works -When you invoke a tool that requires authorization, Arcade's Tool SDK automatically: +When a tool that requires authorization is invoked, the MCP server automatically: -1. Creates a `Context` object +1. Creates an instance of `Context` 2. Passes this object to your tool You can then use the `Context` object to make authenticated requests to external APIs. @@ -48,6 +48,7 @@ await context.log.debug("Debug message") await context.log.info("Information message") await context.log.warning("Warning message") await context.log.error("Error message") +await context.log.log("info", "Info message") # equivalent to await context.log.info("Info message") ``` ### Secrets Management @@ -88,7 +89,7 @@ async def my_tool(context: Context, ...): ## Example Code -The following is an example shows how tools can access runtime features through +The following is an example that shows how tools can access runtime features through `Context`, including logging, secrets, and progress reporting. ### Environment Variables @@ -100,7 +101,7 @@ DATABASE_URL="postgresql://localhost/mydb" -For the code to work, you must define your environment variables in a `.env` file. +For the code to work, you must define your environment variables in a `.env` file at the same directory as your entrypoint file. diff --git a/app/en/home/custom-mcp-server-quickstart/page.mdx b/app/en/home/custom-mcp-server-quickstart/page.mdx index ab470ce49..fe362cb99 100644 --- a/app/en/home/custom-mcp-server-quickstart/page.mdx +++ b/app/en/home/custom-mcp-server-quickstart/page.mdx @@ -62,12 +62,22 @@ In your terminal, run the following command to scaffold a new MCP Server called ```bash arcade new my_server -cd my_server +cd my_server/src/my_server ``` -This generates a complete project with: +This generates a Python module with the following structure: -- **server.py** Main server file with MCPApp and example tools +```bash +my_server/ +├── src/ +│ └── my_server/ +│ ├── __init__.py +│ ├── .env.example +│ └── server.py +└── pyproject.toml +``` + +- **server.py** Entrypoint file with MCPApp and example tools - **pyproject.toml** Dependencies and project configuration - **.env.example** Example `.env` file containing a secret required by one of the generated tools in `server.py` @@ -85,13 +95,13 @@ Secrets are sensitive strings like passwords, api-keys, or other tokens that gra -You can create a `.env` file in the root of your project and add your secret: +You can create a `.env` file at the same directory as your entrypoint file and add your secret: ```env filename=".env" MY_SECRET_KEY="my-secret-value" ``` -The project includes a `.env.example` file with the secret key name and example value. +The generated project includes a `.env.example` file with the secret key name and example value. You can rename it to `.env` to start using it. ```bash diff --git a/app/en/home/deployment/on-prem-mcp/page.mdx b/app/en/home/deployment/on-prem-mcp/page.mdx index debd5d6dd..21f55a3de 100644 --- a/app/en/home/deployment/on-prem-mcp/page.mdx +++ b/app/en/home/deployment/on-prem-mcp/page.mdx @@ -92,8 +92,8 @@ ARCADE_USER_ID= Start your MCP server with HTTP transport: ```bash -# Navigate to your server directory -cd my_server +# Navigate to your entrypoint file +cd my_server/src/my_server # Run with HTTP transport (default) uv run server.py diff --git a/app/en/references/mcp/python/sharing/page.mdx b/app/en/references/mcp/python/sharing/page.mdx index e3f2fadb9..0768aa862 100644 --- a/app/en/references/mcp/python/sharing/page.mdx +++ b/app/en/references/mcp/python/sharing/page.mdx @@ -21,8 +21,8 @@ By default, your MCP server runs locally on `localhost:8000`. To share it: First, start your MCP server with HTTP transport: ```bash -# Navigate to your server directory -cd my_server +# Navigate to your entrypoint file +cd my_server/src/my_server # Run with HTTP transport (default) uv run server.py diff --git a/app/en/references/mcp/python/transports/page.mdx b/app/en/references/mcp/python/transports/page.mdx index 9efffe700..82cf22502 100644 --- a/app/en/references/mcp/python/transports/page.mdx +++ b/app/en/references/mcp/python/transports/page.mdx @@ -95,7 +95,7 @@ app.run(transport="http", host="0.0.0.0", port=8080) When running in HTTP mode, the server provides: -- `GET /health` - Health check endpoint +- `GET /worker/health` - Health check endpoint - `GET /mcp` - SSE endpoint for MCP protocol - `GET /docs` - Swagger UI documentation (debug mode) - `GET /redoc` - ReDoc documentation (debug mode)