golf-mcp 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

golf/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.1"
+__version__ = "0.1.2"

golf/examples/basic/README.md

@@ -1,117 +1,61 @@
-# {{project_name}}
+# GolfMCP Project Boilerplate
 
-A GolfMCP project that provides MCP-compatible tools, resources, and prompts.
+This directory serves as a starting template for new GolfMCP projects. Initialize a project using the `golf init <your-project-name>` command.
+## About GolfMCP
 
-## Getting Started
+GolfMCP is a Python framework designed to build MCP servers with minimal boilerplate. It allows you to define tools, resources, and prompts as simple Python files. These components are then automatically discovered and compiled into a runnable [FastMCP](https://github.com/fastmcp/fastmcp) server.
 
-This project is built with [GolfMCP](https://github.com/yourusername/golfmcp), a Python framework for building MCP servers with zero boilerplate.
+## Getting Started (After `golf init`)
 
-To start the development server with hot reload:
+Once you've initialized your new project from this boilerplate:
 
-```bash
-golf dev
-```
+1.  **Navigate to your project directory:**
+    ```bash
+    cd your-project-name
+    ```
 
-This will watch for file changes and automatically reload the server.
+2.  **Start the development server:**
+    ```bash
+    golf build dev  # For a development build
+    # or
+    golf build prod # For a production build
+    
+    golf run
+    ```
 
 ## Project Structure
 
-- `tools/` - Tool implementations (functions an LLM can call)
-- `resources/` - Resource implementations (data an LLM can read)
-- `prompts/` - Prompt templates (conversations an LLM can use)
-- `golf.json` - Configuration file with settings like telemetry and transport
+Your initialized GolfMCP project will typically have the following structure:
 
-## Adding New Components
-
-### Tools
-
-To add a new tool, create a Python file in the `tools/` directory:
-
-```python
-# tools/my_tool.py
-from pydantic import BaseModel
-from fastmcp import Context
-
-class Input(BaseModel):
-    param1: str
-    param2: int = 42
-
-class Output(BaseModel):
-    result: str
-
-async def run(input: Input, ctx: Context) -> Output:
-    """Description of what my tool does."""
-    await ctx.info(f"Processing {input.param1}...")
-    return MyOutput(result=f"Processed {input.param1} with {input.param2}")
-```
-
-### Resources
-
-To add a new resource, create a Python file in the `resources/` directory:
+-   `tools/`: Directory for your tool implementations (Python files defining functions an LLM can call).
+-   `resources/`: Directory for your resource implementations (Python files defining data an LLM can read).
+-   `prompts/`: Directory for your prompt templates (Python files defining reusable conversation structures).
+-   `golf.json`: The main configuration file for your project, including settings like the server name, port, and transport.
+-   `pre_build.py`: (Optional) A Python script that can be used to run custom logic before the build process begins, such as configuring authentication.
+-   `.env`: File to store environment-specific variables (e.g., API keys). This is created during `golf init`.
 
-```python
-# resources/my_data.py
-resource_uri = "data://my-data"
-
-async def run() -> dict:
-    """Description of the resource."""
-    return {
-        "title": "My Data",
-        "content": "Some valuable information"
-    }
-```
-
-### Sharing Functionality with common.py
-
-For directories with multiple related components (like `tools/payments/` or `resources/weather/`), 
-use a `common.py` file to share functionality:
-
-```python
-# tools/payments/common.py
-class PaymentClient:
-    """Shared payment client implementation."""
-    # Implementation details...
-
-# Create a shared client instance
-payment_client = PaymentClient()
-```
-
-Then import and use the shared functionality in your components:
-
-```python
-# tools/payments/charge.py
-from .common import payment_client
+## Adding New Components
 
-async def run(input):
-    result = await payment_client.create_charge(...)
-    # Rest of implementation...
-```
+To add new functionalities:
 
-This pattern helps organize shared code and makes it easier to build and maintain your project.
+-   **Tools**: Create a new `.py` file in the `tools/` directory.
+-   **Resources**: Create a new `.py` file in the `resources/` directory.
+-   **Prompts**: Create a new `.py` file in the `prompts/` directory.
 
-## Telemetry
+Each Python file should generally define a single component. A module-level docstring in the file will be used as the description for the component. See the example files (e.g., `tools/hello.py`, `resources/info.py`) provided in this boilerplate for reference.
 
-This project includes OpenTelemetry integration for tracing server requests:
+For shared functionality within a component subdirectory (e.g., `tools/payments/common.py`), you can use a `common.py` file.
 
-```json
-// golf.json
-{
-  "telemetry": true,
-  "telemetry_exporter": "console"  // or "otlp_http"
-}
-```
+## Documentation
 
-You can configure it with environment variables:
-- `OTEL_SERVICE_NAME`: Set service name (defaults to app name)
-- `OTEL_TRACES_EXPORTER`: Exporter type ("console" or "otlp_http")
-- `OTEL_EXPORTER_OTLP_ENDPOINT`: OTLP exporter endpoint URL
+For comprehensive details on the GolfMCP framework, including component specifications, advanced configurations, CLI commands, and more, please refer to the official documentation:
 
-## Deployment
+[https://docs.golf.dev](https://docs.golf.dev)
 
-To build the project for deployment:
+---
 
-```bash
-golf build
-```
+Happy Building! 
 
-This creates a standalone FastMCP application in the `dist/` directory. 
+<div align="center">
+Made with ❤️ in San Francisco
+</div>

golf_mcp-0.1.2.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: golf-mcp
+Version: 0.1.2
+Summary: Framework for building MCP servers
+Author-email: Antoni Gmitruk <antoni@golf.dev>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://golf.dev
+Project-URL: Repository, https://github.com/golf-mcp/golf
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.15.4
+Requires-Dist: rich>=14.0.0
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: pydantic>=2.11.0
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: black>=24.10.0
+Requires-Dist: pyjwt>=2.0.0
+Requires-Dist: httpx>=0.28.1
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-api>=1.33.1; extra == "telemetry"
+Requires-Dist: opentelemetry-sdk>=1.33.1; extra == "telemetry"
+Requires-Dist: opentelemetry-instrumentation-asgi>=0.40b0; extra == "telemetry"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=0.40b0; extra == "telemetry"
+Requires-Dist: wrapt>=1.17.0; extra == "telemetry"
+Dynamic: license-file
+
+<div align="center">
+  <img src="./golf-banner.png" alt="Golf Banner">
+  
+  <h1>Golf</h1>
+  
+  <p><strong>Easiest framework for building MCP servers.</strong></p>
+  
+  <p>
+    <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
+    <a href="https://github.com/golf-mcp/golf/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs"></a>
+    <a href="https://github.com/golf-mcp/golf/issues"><img src="https://img.shields.io/badge/support-contact%20author-purple.svg" alt="Support"></a>
+  </p>
+  
+  <p><a href="https://docs.golf.dev">Docs</a></p>
+</div>
+
+## Overview
+
+Golf is a **framework** designed to streamline the creation of MCP server applications. It allows developers to define server's capabilities—*tools*, *prompts*, and *resources*—as simple Python files within a conventional directory structure. Golf then automatically discovers, parses, and compiles these components into a runnable FastMCP server, minimizing boilerplate and accelerating development.
+
+With Golf, you can focus on implementing your agent's logic rather than wrestling with server setup and integration complexities. It's built for developers who want a quick, organized way to build powerful MCP servers.
+
+## Quick Start
+
+Get your Golf project up and running in a few simple steps:
+
+### 1. Install Golf
+
+Ensure you have Python (3.10+ recommended) installed. Then, install Golf using pip:
+
+```bash
+pip install golf-mcp
+```
+
+### 2. Initialize Your Project
+
+Use the Golf CLI to scaffold a new project:
+
+```bash
+golf init your-project-name
+```
+This command creates a new directory (`your-project-name`) with a basic project structure, including example tools, resources, and a `golf.json` configuration file.
+
+### 3. Run the Development Server
+
+Navigate into your new project directory and start the development server:
+
+```bash
+cd your-project-name
+golf build dev
+golf run
+```
+This will start the FastMCP server, typically on `http://127.0.0.1:3000` (configurable in `golf.json`). The `dev` command includes hot reloading, so changes to your component files will automatically restart the server.
+
+That's it! Your Golf server is running and ready for integration.
+
+## Basic Project Structure
+
+A Golf project initialized with `golf init` will have a structure similar to this:
+
+```
+<your-project-name>/
+│
+├─ golf.json          # Main project configuration
+│
+├─ tools/             # Directory for tool implementations
+│   └─ hello.py       # Example tool
+│
+├─ resources/         # Directory for resource implementations
+│   └─ info.py        # Example resource
+│
+├─ prompts/           # Directory for prompt templates
+│   └─ welcome.py     # Example prompt
+│
+├─ .env               # Environment variables (e.g., API keys, server port)
+└─ pre_build.py       # (Optional) Script for pre-build hooks (e.g., auth setup)
+```
+
+-   **`golf.json`**: Configures server name, port, transport, telemetry, and other build settings.
+-   **`tools/`**, **`resources/`**, **`prompts/`**: Contain your Python files, each defining a single component. These directories can also contain nested subdirectories to further organize your components (e.g., `tools/payments/charge.py`). The module docstring of each file serves as the component's description.
+    -   Component IDs are automatically derived from their file path. For example, `tools/hello.py` becomes `hello`, and a nested file like `tools/payments/submit.py` would become `submit-payments` (filename, followed by reversed parent directories under the main category, joined by hyphens).
+-   **`common.py`** (not shown, but can be placed in subdirectories like `tools/payments/common.py`): Used to share code (clients, models, etc.) among components in the same subdirectory.
+
+## Example: Defining a Tool
+
+Creating a new tool is as simple as adding a Python file to the `tools/` directory. The example `tools/hello.py` in the boilerplate looks like this:
+
+```python
+# tools/hello.py
+"""Hello World tool {{project_name}}."""
+
+from pydantic import BaseModel
+
+class Output(BaseModel):
+    """Response from the hello tool."""
+    message: str
+
+async def hello(
+    name: str = "World",
+    greeting: str = "Hello"
+) -> Output:
+    """Say hello to the given name.
+    
+    This is a simple example tool that demonstrates the basic structure
+    of a tool implementation in Golf.
+    """
+    print(f"{greeting} {name}...")
+    return Output(message=f"{greeting}, {name}!")
+
+# Designate the entry point function
+export = hello
+```
+Golf will automatically discover this file. The module docstring `"""Hello World tool {{project_name}}."""` is used as the tool's description. It infers parameters from the `hello` function's signature and uses the `Output` Pydantic model for the output schema. The tool will be registered with the ID `hello`.
+
+## Configuration (`golf.json`)
+
+Key aspects of your Golf server are configured in `golf.json`. The boilerplate provides a starting point like this:
+
+```jsonc
+{
+  "name": "{{project_name}}",          // Will be replaced with your project name
+  "description": "A Golf project", // A default description
+  "host": "127.0.0.1",               // Server host address
+  "port": 3000,                      // Server port
+  "transport": "sse",                // 'sse', 'streamable-http', or 'stdio'
+  "opentelemetry_enabled": false,    // OpenTelemetry disabled by default - we're working on this as a feature
+  "opentelemetry_default_exporter": "console"
+}
+```
+## Roadmap
+
+We are actively developing Golf. Here's what's on our current roadmap:
+
+
+## Documentation
+
+For more information, please visit our official documentation:
+
+[https://docs.golf.dev](https://docs.golf.dev)
+
+<div align="center">
+Made with ❤️ in Warsaw, Poland and SF
+</div>

{golf_mcp-0.1.1.dist-info → golf_mcp-0.1.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-golf/__init__.py,sha256=8oAxKUG747GUokmxjkrWejyJa5yPNEsoJDlXxoedxTw,21
+golf/__init__.py,sha256=K5SiDdEGYMpdqXThrqwTqECJJBOQNTQDrnpc2K5mzKs,21
 golf/auth/__init__.py,sha256=0cfMJsLsOAsA4gHynyPGDkrjB90s3xsGSFoCEWg-y6o,3999
 golf/auth/helpers.py,sha256=TqMlOzwtcQcrZ6en2WVkzH0TSQ0RsoDRObpi_rR0Ie4,1681
 golf/auth/oauth.py,sha256=MGtuKMSt77yihuZiuiEm33xAlXJynIMcFmMLZRlppdg,31525
@@ -19,7 +19,7 @@ golf/core/transformer.py,sha256=3mr4_K4l1HZl1WQWSt9NKEhB5oi3b7kJnniseYEfrcI,5573
 golf/examples/__init__.py,sha256=Nqnn8clbgv-5l0PgxcTOldg8mkMKrFn4TvPL-rYUUGg,1
 golf/examples/basic/.env,sha256=CRh4u1yXPCbjjgUKUMUgw51aOBdVFEgY748z7WgfkVc,156
 golf/examples/basic/.env.example,sha256=gCTFcabTvr_-Rg3kTGmi63JQtCEOwMu4U5jTa1GM66U,123
-golf/examples/basic/README.md,sha256=Hp6mQlC2pj_JKd55fO1O50zTxmqA55JldwoVOXUSCPA,2882
+golf/examples/basic/README.md,sha256=-mY3R6AAnkXT9FPkALDrJtdf9IyKDvuqjsrLAMTLRYI,2663
 golf/examples/basic/golf.json,sha256=JThi6EC93trGqECo3ryD3MhDcyR9Haub8kYvmYo4yjQ,213
 golf/examples/basic/pre_build.py,sha256=VVYtBSCy4Xjg1Ocpl8ZwEr7VCVqPSSkDEzrTfQkAQKY,1037
 golf/examples/basic/prompts/welcome.py,sha256=LgT1eQewe0J08I5WFBv4RrgDr6yn4a4ww6XQ8k3sTVk,822
@@ -33,9 +33,9 @@ golf/examples/basic/tools/hello.py,sha256=hJUMraxgi5g0gzhPbUZGOeAbiKZX4BTr1L64SE
 golf/examples/basic/tools/payments/charge.py,sha256=jLOyQmbpRm8cOIK2JXSirPmQGXDM-yHvg7ruv72j6qU,1287
 golf/examples/basic/tools/payments/common.py,sha256=z5shSOZizUEnxBmGUSYghxmNwIvuhg-yfXKIfPWgV04,1292
 golf/examples/basic/tools/payments/refund.py,sha256=_HG4dDeki8FyKCtWs5fXYeLpUsrc_SAx3vxAIS7Icf0,1302
-golf_mcp-0.1.1.dist-info/licenses/LICENSE,sha256=5_j2f6fTJmvfmUewzElhkpAaXg2grVoxKouOA8ihV6E,11348
-golf_mcp-0.1.1.dist-info/METADATA,sha256=mXLS9WPAwviBjcyjW9BRHVOlro9Uc0M90l5YVSLZtm4,2421
-golf_mcp-0.1.1.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
-golf_mcp-0.1.1.dist-info/entry_points.txt,sha256=5y7rHYM8jGpU-nfwdknCm5XsApLulqsnA37MO6BUTYg,43
-golf_mcp-0.1.1.dist-info/top_level.txt,sha256=BQToHcBUufdyhp9ONGMIvPE40jMEtmI20lYaKb4hxOg,5
-golf_mcp-0.1.1.dist-info/RECORD,,
+golf_mcp-0.1.2.dist-info/licenses/LICENSE,sha256=5_j2f6fTJmvfmUewzElhkpAaXg2grVoxKouOA8ihV6E,11348
+golf_mcp-0.1.2.dist-info/METADATA,sha256=pgiA91H0Gk_AwkI8Y-GDHVpN0TtB4DAnwUIWVjwk3XM,7365
+golf_mcp-0.1.2.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
+golf_mcp-0.1.2.dist-info/entry_points.txt,sha256=5y7rHYM8jGpU-nfwdknCm5XsApLulqsnA37MO6BUTYg,43
+golf_mcp-0.1.2.dist-info/top_level.txt,sha256=BQToHcBUufdyhp9ONGMIvPE40jMEtmI20lYaKb4hxOg,5
+golf_mcp-0.1.2.dist-info/RECORD,,

golf_mcp-0.1.1.dist-info/METADATA

@@ -1,78 +0,0 @@
-Metadata-Version: 2.4
-Name: golf-mcp
-Version: 0.1.1
-Summary: Framework for building MCP servers
-Author-email: Antoni Gmitruk <antoni@golf.dev>
-License-Expression: Apache-2.0
-Project-URL: Homepage, https://golf.dev
-Project-URL: Repository, https://github.com/golf-mcp/golf
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: typer>=0.15.4
-Requires-Dist: rich>=14.0.0
-Requires-Dist: fastmcp>=2.0.0
-Requires-Dist: pydantic>=2.11.0
-Requires-Dist: python-dotenv>=1.1.0
-Requires-Dist: black>=24.10.0
-Requires-Dist: pyjwt>=2.0.0
-Requires-Dist: httpx>=0.28.1
-Provides-Extra: telemetry
-Requires-Dist: opentelemetry-api>=1.33.1; extra == "telemetry"
-Requires-Dist: opentelemetry-sdk>=1.33.1; extra == "telemetry"
-Requires-Dist: opentelemetry-instrumentation-asgi>=0.40b0; extra == "telemetry"
-Requires-Dist: opentelemetry-exporter-otlp-proto-http>=0.40b0; extra == "telemetry"
-Requires-Dist: wrapt>=1.17.0; extra == "telemetry"
-Dynamic: license-file
-
-# GolfMCP
-
-A Pythonic framework for building Model Context Protocol (MCP) servers with zero boilerplate.
-
-## Features
-
-* 🚀 **Zero-to-live in under 90 seconds**: Quick setup and deployment
-* 💡 **Convention over configuration**: Minimal boilerplate
-* 🔄 **Fast feedback**: Hot-reload during development (≤ 500 ms)
-* 📂 **Nested folder support**: Organize your tools, resources, and prompts
-* 🔌 **Pluggable auth & deploy**: Built-in providers for OAuth, Vercel, Fly.io, etc.
-* 🛠️ **Delegates protocol compliance to FastMCP**: Focus on your logic, not the wire format
-
-## Installation
-
-```bash
-pip install golfmcp
-```
-
-## Quick Start
-
-Initialize a new project:
-
-```bash
-golf init my-mcp-project
-cd my-mcp-project
-```
-
-Start the development server with hot-reload:
-
-```bash
-golf dev
-```
-
-## Documentation
-
-For detailed documentation, visit [docs](https://golfmcp.docs.example.com/).
-
-## License
-
-MIT License