meta-ads-mcp 0.3.7__tar.gz → 0.3.8__tar.gz

{meta_ads_mcp-0.3.7 → meta_ads_mcp-0.3.8}/.gitignore

@@ -20,3 +20,13 @@ uv.lock
 
 # Generated content
 ad_creatives/
+
+# Debug and development files
+debug/
+*.pyc
+.pytest_cache/
+
+# Keep organized directories but exclude some debug content
+!debug/README.md
+
+internal/

{meta_ads_mcp-0.3.7 → meta_ads_mcp-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-ads-mcp
-Version: 0.3.7
+Version: 0.3.8
 Summary: Model Calling Protocol (MCP) plugin for interacting with Meta Ads API
 Project-URL: Homepage, https://github.com/nictuku/meta-ads-mcp
 Project-URL: Bug Tracker, https://github.com/nictuku/meta-ads-mcp/issues
@@ -13,7 +13,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.26.0
-Requires-Dist: mcp[cli]>=1.6.0
+Requires-Dist: mcp[cli]>=1.9.0
 Requires-Dist: pathlib>=1.0.1
 Requires-Dist: pillow>=10.0.0
 Requires-Dist: python-dateutil>=2.8.2
@@ -27,10 +27,14 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
 
 > **DISCLAIMER:** This is an unofficial third-party tool and is not associated with, endorsed by, or affiliated with Meta in any way. This project is maintained independently and uses Meta's public APIs according to their terms of service. Meta, Facebook, Instagram, and other Meta brand names are trademarks of their respective owners.
 
-**Screenshot**: Using an LLM to understand your ad performance:
+[![Meta Ads MCP Server Demo](https://github.com/user-attachments/assets/3e605cee-d289-414b-814c-6299e7f3383e)](https://github.com/user-attachments/assets/3e605cee-d289-414b-814c-6299e7f3383e)
 
-![Meta Ads MCP in action: Visualize ad performance metrics and creative details directly in Claude or your favorite MCP client, with rich insights about campaign reach, engagement, and costs](./images/meta-ads-example.png)
 
+## Community & Support
+
+- [Discord](https://discord.gg/hNxpJcqM52). Join the community.
+- [Email Support](info@pipeboard.co). Email us for support.
+  
 ## Quick Start
 
 1. Sign-up to [Pipeboard](https://pipeboard.co) to authenticate with Meta (alternatively, you can setup your own [custom meta app](CUSTOM_META_APP.md))
@@ -157,6 +161,10 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
 }
 ```
 
+## Transports
+
+Meta Ads MCP uses **stdio transport** by default, which works with MCP clients like Claude Desktop and Cursor. For web applications and direct HTTP API access, see [STREAMABLE_HTTP_SETUP.md](STREAMABLE_HTTP_SETUP.md) for streamable HTTP transport configuration.
+
 ### Available MCP Tools
 
 1. `mcp_meta_ads_get_ad_accounts`

{meta_ads_mcp-0.3.7 → meta_ads_mcp-0.3.8}/README.md

@@ -4,10 +4,14 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
 
 > **DISCLAIMER:** This is an unofficial third-party tool and is not associated with, endorsed by, or affiliated with Meta in any way. This project is maintained independently and uses Meta's public APIs according to their terms of service. Meta, Facebook, Instagram, and other Meta brand names are trademarks of their respective owners.
 
-**Screenshot**: Using an LLM to understand your ad performance:
+[![Meta Ads MCP Server Demo](https://github.com/user-attachments/assets/3e605cee-d289-414b-814c-6299e7f3383e)](https://github.com/user-attachments/assets/3e605cee-d289-414b-814c-6299e7f3383e)
 
-![Meta Ads MCP in action: Visualize ad performance metrics and creative details directly in Claude or your favorite MCP client, with rich insights about campaign reach, engagement, and costs](./images/meta-ads-example.png)
 
+## Community & Support
+
+- [Discord](https://discord.gg/hNxpJcqM52). Join the community.
+- [Email Support](info@pipeboard.co). Email us for support.
+  
 ## Quick Start
 
 1. Sign-up to [Pipeboard](https://pipeboard.co) to authenticate with Meta (alternatively, you can setup your own [custom meta app](CUSTOM_META_APP.md))
@@ -134,6 +138,10 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
 }
 ```
 
+## Transports
+
+Meta Ads MCP uses **stdio transport** by default, which works with MCP clients like Claude Desktop and Cursor. For web applications and direct HTTP API access, see [STREAMABLE_HTTP_SETUP.md](STREAMABLE_HTTP_SETUP.md) for streamable HTTP transport configuration.
+
 ### Available MCP Tools
 
 1. `mcp_meta_ads_get_ad_accounts`

{meta_ads_mcp-0.3.7 → meta_ads_mcp-0.3.8}/RELEASE.md

@@ -4,35 +4,27 @@ This repository uses GitHub Actions to automatically publish releases to PyPI. H
 
 ## Automated Publishing
 
-### Setup Required
-
-1. **Configure Trusted Publishing on PyPI** (Recommended):
-   - Go to your PyPI project page: https://pypi.org/manage/project/meta-ads-mcp/
-   - Navigate to "Publishing" → "Add a new pending publisher"
-   - Fill in the details:
-     - Owner: `nictuku` (your GitHub username/org)
-     - Repository name: `meta-ads-mcp`
-     - Workflow name: `publish.yml`
-     - Environment name: `release`
-   
-   This eliminates the need for API tokens and is more secure.
+### Setup Status
 
-2. **Alternative: API Token Method**:
-   - If you prefer using API tokens, go to PyPI → Account Settings → API tokens
-   - Create a token with scope limited to this project
-   - Add it as a repository secret named `PYPI_API_TOKEN`
-   - Modify `.github/workflows/publish.yml` to use the token instead of trusted publishing
+✅ **Trusted Publishing Configured**: The repository is already set up with PyPI trusted publishing using the `release` environment.
 
 ### Creating a Release
 
-1. **Update the version** in `pyproject.toml`:
+1. **Update the version** in both files:
+   
+   In `pyproject.toml`:
    ```toml
    version = "0.3.8"  # Increment as needed
    ```
+   
+   In `meta_ads_mcp/__init__.py`:
+   ```python
+   __version__ = "0.3.8"  # Must match pyproject.toml
+   ```
 
-2. **Commit and push** the version change:
+2. **Commit and push** the version changes:
    ```bash
-   git add pyproject.toml
+   git add pyproject.toml meta_ads_mcp/__init__.py
    git commit -m "Bump version to 0.3.8"
    git push origin main
    ```
@@ -53,11 +45,11 @@ This repository uses GitHub Actions to automatically publish releases to PyPI. H
 ## Workflows
 
 ### `publish.yml`
-- **Triggers**: When a GitHub release is published
+- **Triggers**: When a GitHub release is published, or manual workflow dispatch
 - **Purpose**: Builds and publishes the package to PyPI
-- **Environment**: Uses the `release` environment for additional security
+- **Security**: Uses trusted publishing with OIDC tokens (no API keys needed)
 
-### `test.yml`
+### `test.yml` (if present)
 - **Triggers**: On pushes and pull requests to main/master
 - **Purpose**: Tests package building and installation across Python versions
 - **Matrix**: Tests Python 3.10, 3.11, and 3.12
@@ -80,12 +72,13 @@ python -m twine upload dist/*
 ## Version Management
 
 - Follow semantic versioning (SemVer): `MAJOR.MINOR.PATCH`
-- Update version in `pyproject.toml` before creating releases
+- **Important**: Update version in BOTH `pyproject.toml` and `meta_ads_mcp/__init__.py`
 - The git tag should match the version (e.g., `v0.3.8` for version `0.3.8`)
+- Keep versions synchronized between the two files
 
 ## Security Notes
 
 - Trusted publishing is preferred over API tokens
-- The `release` environment can be configured with additional protection rules
+- Uses GitHub's OIDC tokens for secure authentication to PyPI
 - Only maintainers should be able to create releases
 - All builds run in isolated GitHub-hosted runners 

meta_ads_mcp-0.3.8/STREAMABLE_HTTP_SETUP.md

@@ -0,0 +1,350 @@
+# Streamable HTTP Transport Setup
+
+## Overview
+
+Meta Ads MCP supports **Streamable HTTP Transport**, which allows you to run the server as a standalone HTTP API. This enables direct integration with web applications, custom dashboards, and any system that can make HTTP requests.
+
+## Quick Start
+
+### 1. Start the HTTP Server
+
+```bash
+# Basic HTTP server (default: localhost:8080)
+python -m meta_ads_mcp --transport streamable-http
+
+# Custom host and port
+python -m meta_ads_mcp --transport streamable-http --host 0.0.0.0 --port 9000
+```
+
+### 2. Set Authentication
+
+Set your Pipeboard token as an environment variable. This is optional for HTTP transport if you provide the token in the header, but it can be useful for command-line use.
+
+```bash
+export PIPEBOARD_API_TOKEN=your_pipeboard_token
+```
+
+### 3. Make HTTP Requests
+
+The server accepts JSON-RPC 2.0 requests at the `/mcp/` endpoint. Use the `Authorization` header to provide your token.
+
+```bash
+curl -X POST http://localhost:8080/mcp/ \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer your_pipeboard_token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "tools/call",
+    "id": 1,
+    "params": {
+      "name": "get_ad_accounts",
+      "arguments": {"limit": 5}
+    }
+  }'
+```
+
+## Configuration Options
+
+### Command Line Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `--transport` | Transport mode | `stdio` |
+| `--host` | Server host address | `localhost` |
+| `--port` | Server port | `8080` |
+
+### Examples
+
+```bash
+# Local development server
+python -m meta_ads_mcp --transport streamable-http --host localhost --port 8080
+
+# Production server (accessible externally)
+python -m meta_ads_mcp --transport streamable-http --host 0.0.0.0 --port 8080
+
+# Custom port
+python -m meta_ads_mcp --transport streamable-http --port 9000
+```
+
+## Authentication
+
+### Primary Method: Bearer Token (Recommended)
+
+1. Sign up at [Pipeboard.co](https://pipeboard.co)
+2. Generate an API token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens)
+3. Include the token in the `Authorization` HTTP header:
+
+```bash
+curl -H "Authorization: Bearer your_pipeboard_token" \
+     -X POST http://localhost:8080/mcp/ \
+     -H "Content-Type: application/json" \
+     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+### Alternative Method: Direct Meta Token
+
+If you have a Meta Developer App, you can use a direct access token via the `X-META-ACCESS-TOKEN` header. This is less common.
+
+```bash
+curl -H "X-META-ACCESS-TOKEN: your_meta_access_token" \
+     -X POST http://localhost:8080/mcp/ \
+     -H "Content-Type: application/json" \
+     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+## Available Endpoints
+
+### Server URL Structure
+
+**Base URL**: `http://localhost:8080`  
+**MCP Endpoint**: `/mcp/`
+
+### MCP Protocol Methods
+
+| Method | Description |
+|--------|-------------|
+| `initialize` | Initialize MCP session and exchange capabilities |
+| `tools/list` | Get list of all available Meta Ads tools |
+| `tools/call` | Execute a specific tool with parameters |
+
+### Response Format
+
+All responses follow JSON-RPC 2.0 format:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    // Tool response data
+  }
+}
+```
+
+## Example Usage
+
+### 1. Initialize Session
+
+```bash
+curl -X POST http://localhost:8080/mcp/ \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your_token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "initialize",
+    "id": 1,
+    "params": {
+      "protocolVersion": "2024-11-05",
+      "capabilities": {"roots": {"listChanged": true}},
+      "clientInfo": {"name": "my-app", "version": "1.0.0"}
+    }
+  }'
+```
+
+### 2. List Available Tools
+
+```bash
+curl -X POST http://localhost:8080/mcp/ \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your_token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "tools/list",
+    "id": 2
+  }'
+```
+
+### 3. Get Ad Accounts
+
+```bash
+curl -X POST http://localhost:8080/mcp/ \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your_token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "tools/call",
+    "id": 3,
+    "params": {
+      "name": "get_ad_accounts",
+      "arguments": {"limit": 10}
+    }
+  }'
+```
+
+### 4. Get Campaign Performance
+
+```bash
+curl -X POST http://localhost:8080/mcp/ \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your_token" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "tools/call",
+    "id": 4,
+    "params": {
+      "name": "get_insights",
+      "arguments": {
+        "object_id": "act_701351919139047",
+        "time_range": "last_30d",
+        "level": "campaign"
+      }
+    }
+  }'
+```
+
+## Client Examples
+
+### Python Client
+
+```python
+import requests
+import json
+
+class MetaAdsMCPClient:
+    def __init__(self, base_url="http://localhost:8080", token=None):
+        self.base_url = base_url
+        self.endpoint = f"{base_url}/mcp/"
+        self.headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream"
+        }
+        if token:
+            self.headers["Authorization"] = f"Bearer {token}"
+    
+    def call_tool(self, tool_name, arguments=None):
+        payload = {
+            "jsonrpc": "2.0",
+            "method": "tools/call",
+            "id": 1,
+            "params": {"name": tool_name}
+        }
+        if arguments:
+            payload["params"]["arguments"] = arguments
+        
+        response = requests.post(self.endpoint, headers=self.headers, json=payload)
+        return response.json()
+
+# Usage
+client = MetaAdsMCPClient(token="your_pipeboard_token")
+result = client.call_tool("get_ad_accounts", {"limit": 5})
+print(json.dumps(result, indent=2))
+```
+
+### JavaScript/Node.js Client
+
+```javascript
+const axios = require('axios');
+
+class MetaAdsMCPClient {
+    constructor(baseUrl = 'http://localhost:8080', token = null) {
+        this.baseUrl = baseUrl;
+        this.endpoint = `${baseUrl}/mcp/`;
+        this.headers = {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json, text/event-stream'
+        };
+        if (token) {
+            this.headers['Authorization'] = `Bearer ${token}`;
+        }
+    }
+
+    async callTool(toolName, arguments = null) {
+        const payload = {
+            jsonrpc: '2.0',
+            method: 'tools/call',
+            id: 1,
+            params: { name: toolName }
+        };
+        if (arguments) {
+            payload.params.arguments = arguments;
+        }
+
+        try {
+            const response = await axios.post(this.endpoint, payload, { headers: this.headers });
+            return response.data;
+        } catch (error) {
+            return { error: error.message };
+        }
+    }
+}
+
+// Usage
+const client = new MetaAdsMCPClient('http://localhost:8080', 'your_pipeboard_token');
+client.callTool('get_ad_accounts', { limit: 5 })
+    .then(result => console.log(JSON.stringify(result, null, 2)));
+```
+
+## Production Deployment
+
+### Security Considerations
+
+1. **Use HTTPS**: In production, run behind a reverse proxy with SSL/TLS
+2. **Authentication**: Always use valid Bearer tokens.
+3. **Network Security**: Configure firewalls and access controls appropriately
+4. **Rate Limiting**: Consider implementing rate limiting for public APIs
+
+### Docker Deployment
+
+```dockerfile
+FROM python:3.10-slim
+
+WORKDIR /app
+COPY . .
+RUN pip install -e .
+
+EXPOSE 8080
+
+CMD ["python", "-m", "meta_ads_mcp", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8080"]
+```
+
+### Environment Variables
+
+```bash
+# For Pipeboard-based authentication. The token will be used for stdio,
+# but for HTTP it should be passed in the Authorization header.
+export PIPEBOARD_API_TOKEN=your_pipeboard_token
+
+# Optional (for custom Meta apps)
+export META_APP_ID=your_app_id
+export META_APP_SECRET=your_app_secret
+
+# Optional (for direct Meta token)
+export META_ACCESS_TOKEN=your_access_token
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Connection Refused**: Ensure the server is running and accessible on the specified port.
+2. **Authentication Failed**: Verify your Bearer token is valid and included in the `Authorization` header.
+3. **404 Not Found**: Make sure you're using the correct endpoint (`/mcp/`).
+4. **JSON-RPC Errors**: Check that your request follows the JSON-RPC 2.0 format.
+
+### Debug Mode
+
+Enable verbose logging by setting the log level in your environment if the application supports it, or check the application's logging configuration. The current implementation logs to a file.
+
+### Health Check
+
+Test if the server is running by sending a `tools/list` request:
+
+```bash
+curl -X POST http://localhost:8080/mcp/ \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your_token" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+## Migration from stdio
+
+If you're currently using stdio transport with MCP clients, you can support both stdio for local clients and HTTP for web applications. The application can only run in one mode at a time, so you may need to run two separate instances if you need both simultaneously.
+
+1. **Keep existing MCP client setup** (Claude Desktop, Cursor, etc.) using stdio.
+2. **Add HTTP transport** for web applications and custom integrations by running a separate server instance with the `--transport streamable-http` flag.
+3. **Use the same authentication method**:
+    - For stdio, the `PIPEBOARD_API_TOKEN` environment variable is used.
+    - For HTTP, pass the token in the `Authorization: Bearer <token>` header.
+
+Both transports access the same Meta Ads functionality and use the same underlying authentication system. 

meta_ads_mcp-0.3.8/debug/README.md

@@ -0,0 +1,40 @@
+# Debug and Legacy Files
+
+This directory contains debug scripts, development tools, and legacy test files that were used during the development process.
+
+## 🚨 **Important Note**
+These files are **NOT** for production use. They are kept for:
+- Development reference
+- Debugging specific issues
+- Historical context of implementation decisions
+
+## Files
+
+### Authentication & Token Flow Debug
+- `debug_auth_integration.py` - Debug authentication integration between HTTP headers and tool execution
+- `debug_token_flow.py` - Debug Meta API token validation and flow
+- `debug_meta_api_tool.py` - Debug Meta API tool functionality
+
+### Server Configuration Debug  
+- `debug_fastmcp_config.py` - Debug FastMCP server configuration and HTTP transport setup
+
+### Legacy Test Files
+- `test_streamable_http_old.py` - Original HTTP transport test (superseded by `tests/test_http_transport.py`)
+- `test_meta_ads_auth.py` - Legacy authentication test
+- `test_pipeboard_auth.py` - Legacy Pipeboard authentication test
+
+## Usage Guidelines
+
+**For Development:**
+- These scripts may have hardcoded values, test tokens, or development-specific configurations
+- They may not follow production coding standards
+- Use them as reference only
+
+**For Production:**
+- Use the organized `tests/` directory for proper testing
+- Use the `examples/` directory for integration examples
+- Use the main package (`meta_ads_mcp/`) for actual functionality
+
+## Cleanup Policy
+
+Files in this directory may be removed in future releases once they're no longer needed for debugging or reference purposes. 

meta_ads_mcp-0.3.8/examples/README.md

@@ -0,0 +1,36 @@
+# Meta Ads MCP Examples
+
+This directory contains example scripts and usage demonstrations for the Meta Ads MCP server.
+
+## Files
+
+### `http_client.py`
+A complete example HTTP client that demonstrates how to interact with the Meta Ads MCP server using the HTTP transport.
+
+**Features:**
+- Shows how to authenticate with Pipeboard tokens or Meta access tokens
+- Demonstrates all basic MCP operations (initialize, list tools, call tools)
+- Includes error handling and response formatting
+- Ready-to-use client class for integration
+
+**Usage:**
+```bash
+# Start the MCP server
+python -m meta_ads_mcp --transport streamable-http --port 8080
+
+# Run the example (in another terminal)
+cd examples
+python http_client.py
+```
+
+**Authentication:**
+- Set `PIPEBOARD_API_TOKEN` environment variable for Pipeboard auth
+- Or pass `meta_access_token` parameter for direct Meta API auth
+
+## Adding New Examples
+
+When adding new example files:
+1. Include comprehensive docstrings
+2. Add usage instructions in comments
+3. Update this README with file descriptions
+4. Follow the same authentication patterns as `http_client.py`