From dcd0a02389aeb590086273692cc30b4255c8d300 Mon Sep 17 00:00:00 2001 From: Eric Gustin <34000337+EricGustin@users.noreply.github.com> Date: Fri, 3 Oct 2025 12:47:32 -0700 Subject: [PATCH] Fix bug and update readme (#599) The README didn't make any sense for a server developer. Especially when viewed from PyPI Fix bug so now stdio works --- README.md | 110 +++++++++++------- libs/arcade-cli/arcade_cli/new.py | 2 +- .../arcade_mcp_server/mcp_app.py | 2 - libs/arcade-mcp-server/pyproject.toml | 2 +- pyproject.toml | 6 +- 5 files changed, 76 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index a4f4b060..44026c79 100644 --- a/README.md +++ b/README.md @@ -37,69 +37,101 @@ Quickstart • Contact Us -# Arcade AI Platform - -Arcade is a developer platform that lets you build, deploy, and manage tools for AI agents. - -This repository contains the core Arcade libraries, organized as separate packages for maximum flexibility and modularity: - -- **arcade-core** - Core platform functionality and schemas | [Source code](https://github.com/ArcadeAI/arcade-mcp/tree/main/libs/arcade-core) | `pip install arcade-core` | -- **arcade-mcp-server** - MCP Server Development Framework | [Source code](https://github.com/ArcadeAI/arcade-mcp/tree/main/libs/arcade-mcp-server) | `pip install arcade-mcp-server` | -- **arcade-tdk** - Tool Development Kit with the `@tool` decorator | [Source code](https://github.com/ArcadeAI/arcade-mcp/tree/main/libs/arcade-tdk) | `pip install arcade-tdk` | -- **arcade-serve** - Serving infrastructure for workers and MCP servers | [Source code](https://github.com/ArcadeAI/arcade-mcp/tree/main/libs/arcade-serve) | `pip install arcade-serve` | -- **arcade-evals** - Evaluation framework for testing tool performance | [Source code](https://github.com/ArcadeAI/arcade-mcp/tree/main/libs/arcade-evals) | `pip install 'arcade-mcp[evals]` | -- **arcade-cli** - Command-line interface for the Arcade platform | [Source code](https://github.com/ArcadeAI/arcade-mcp/tree/main/libs/arcade-cli) | `pip install arcade-mcp` | - -![diagram](https://github.com/user-attachments/assets/1a567e5f-d6b4-4b1e-9918-c401ad232ebb) +# Arcade MCP Server Framework **To learn more about Arcade.dev, check out our [documentation](https://docs.arcade.dev/home).** +**To learn more about the Arcade MCP Server Framework, check out our [Arcade MCP documentation](https://python.mcp.arcade.dev/)** + _Pst. hey, you, give us a star if you like it!_ GitHub stars -## Quick Start +### Quick Start: Create a New Server -### Installation - -For development, install all packages with dependencies using uv workspace: +The fastest way to get started is with the `arcade new` command, which creates a complete MCP server project: ```bash -# Install all packages and dev dependencies -uv sync --extra all --dev +# Install the CLI +uv pip install arcade-mcp -# Or use the Makefile (includes pre-commit hooks) -make install +# Create a new server project +arcade new my_server + +# Navigate to the project +cd my_server ``` -For production use, install individual packages as needed: +This generates a complete project with: -```bash -pip install arcade-mcp # CLI -pip install 'arcade-mcp[evals]' # CLI + Evaluation framework -pip install 'arcade-mcp[all]' # CLI + Serving infra + eval framework + TDK -pip install arcade_serve # Serving infrastructure -pip install arcade-tdk # Tool Development Kit +- **server.py** - Main server 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` + +The generated `server.py` includes proper command-line argument handling: + +```python +#!/usr/bin/env python3 +import sys +from typing import Annotated +from arcade_mcp_server import MCPApp + +app = MCPApp(name="my_server", version="1.0.0") + +@app.tool +def greet(name: Annotated[str, "Name to greet"]) -> str: + """Greet someone by name.""" + return f"Hello, {name}!" + +if __name__ == "__main__": + transport = sys.argv[1] if len(sys.argv) > 1 else "http" + app.run(transport=transport, host="127.0.0.1", port=8000) ``` -### Development +This approach gives you: +- **Complete Project Setup** - Everything you need in one command -Use the Makefile for standard tasks: +- **Best Practices** - Proper dependency management with pyproject.toml + +- **Example Code** - Learn from working examples of common patterns + +- **Production Ready** - Structured for growth and deployment + +### Running Your Server + +Run your server directly with Python: ```bash -# Run tests -make test +# Run with HTTP transport (default) +uv run server.py -# Run linting and type checking -make check +# Run with stdio transport (for Claude Desktop) +uv run server.py stdio -# Build all packages -make build +# Or use python directly +python server.py http +python server.py stdio +``` -# See all available commands -make help +Your server will start and listen for connections. With HTTP transport, you can access the API docs at http://127.0.0.1:8000/docs. + +### Configure MCP Clients + +Once your server is running, connect it to your favorite AI assistant: + +```bash +# Configure Claude Desktop (configures for stdio) +arcade configure claude --from-local + +# Configure Cursor (configures for http streamable) +arcade configure cursor --from-local + +# Configure VS Code (configures for http streamable) +arcade configure vscode --from-local ``` ## Client Libraries diff --git a/libs/arcade-cli/arcade_cli/new.py b/libs/arcade-cli/arcade_cli/new.py index 74d1ac28..d4c67fd7 100644 --- a/libs/arcade-cli/arcade_cli/new.py +++ b/libs/arcade-cli/arcade_cli/new.py @@ -26,7 +26,7 @@ ARCADE_TDK_MIN_VERSION = "3.0.0" ARCADE_TDK_MAX_VERSION = "4.0.0" ARCADE_SERVE_MIN_VERSION = "3.0.0" ARCADE_SERVE_MAX_VERSION = "4.0.0" -ARCADE_MCP_SERVER_MIN_VERSION = "1.0.0" +ARCADE_MCP_SERVER_MIN_VERSION = "1.0.1" ARCADE_MCP_SERVER_MAX_VERSION = "2.0.0" diff --git a/libs/arcade-mcp-server/arcade_mcp_server/mcp_app.py b/libs/arcade-mcp-server/arcade_mcp_server/mcp_app.py index 4d902172..7ae9081a 100644 --- a/libs/arcade-mcp-server/arcade_mcp_server/mcp_app.py +++ b/libs/arcade-mcp-server/arcade_mcp_server/mcp_app.py @@ -226,8 +226,6 @@ class MCPApp: asyncio.run( run_stdio_server( catalog=self._catalog, - port=port, - reload=reload, **self.server_kwargs, ) ) diff --git a/libs/arcade-mcp-server/pyproject.toml b/libs/arcade-mcp-server/pyproject.toml index 80318c6e..75c44d4a 100644 --- a/libs/arcade-mcp-server/pyproject.toml +++ b/libs/arcade-mcp-server/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "arcade-mcp-server" -version = "1.0.0" +version = "1.0.1" description = "Model Context Protocol (MCP) server framework for Arcade.dev" readme = "README.md" authors = [{ name = "Arcade.dev" }] diff --git a/pyproject.toml b/pyproject.toml index a6a2313e..507796a3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "arcade-mcp" -version = "1.0.0" +version = "1.0.1" description = "Arcade.dev - Tool Calling platform for Agents" readme = "README.md" license = {file = "LICENSE"} @@ -21,7 +21,7 @@ requires-python = ">=3.10" dependencies = [ # CLI dependencies - "arcade-mcp-server>=1.0.0,<2.0.0", + "arcade-mcp-server>=1.0.1,<2.0.0", "arcade-core>=3.0.0,<4.0.0", "typer==0.10.0", "rich==13.9.4", @@ -42,7 +42,7 @@ all = [ "pytz>=2024.1", "python-dateutil>=2.8.2", # mcp - "arcade-mcp-server>=1.0.0,<2.0.0", + "arcade-mcp-server>=1.0.1,<2.0.0", # serve "arcade-serve>=3.0.0,<4.0.0", # tdk