Metadata-Version: 2.5
Name: crewai-tokportal
Version: 0.1.0
Summary: CrewAI integration for TokPortal — managed TikTok, Instagram and YouTube accounts as CrewAI tools (native tools + remote MCP server).
Project-URL: Homepage, https://developers.tokportal.com
Project-URL: Repository, https://github.com/tokportal/crewai-tokportal
Project-URL: Documentation, https://developers.tokportal.com/mcp
Project-URL: Issues, https://github.com/tokportal/crewai-tokportal/issues
Author-email: TokPortal <team@tokportal.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,automation,crewai,crewai-tools,instagram,mcp,social-media,tiktok,tokportal,tools,youtube
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: crewai>=1.0
Requires-Dist: pydantic>=2
Requires-Dist: tokportal>=0.1.0
Provides-Extra: mcp
Requires-Dist: crewai-tools[mcp]>=1.0; extra == 'mcp'
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# crewai-tokportal

[![PyPI](https://img.shields.io/pypi/v/crewai-tokportal.svg)](https://pypi.org/project/crewai-tokportal/)
[![CI](https://github.com/tokportal/crewai-tokportal/actions/workflows/ci.yml/badge.svg)](https://github.com/tokportal/crewai-tokportal/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[CrewAI](https://crewai.com) integration for **TokPortal**.

**TokPortal is the managed social infrastructure API: real TikTok, Instagram and YouTube accounts created, warmed and operated by human account managers in 16+ countries — exposed as a REST API and an MCP server. No OAuth per account, no 25-posts/day cap, no app review.**

Two ways to give your crew TokPortal super-powers:

| Mode | What you get | When to use |
|---|---|---|
| **Native tools** (`tokportal_tools()`) | 6 `crewai.tools.BaseTool` subclasses wrapping the [`tokportal`](https://pypi.org/project/tokportal/) Python SDK: credit balance, create bundle, configure video, publish bundle, get bundle, list accounts | Lightweight, no MCP dependency |
| **MCP** (`tokportal_mcp_server()` / `tokportal_mcp_adapter()`) | Every tool of the remote TokPortal MCP server (90+ operations: uploads, warming, analytics, webhooks, comments, bans…) | Full API surface |

## Installation

```bash
pip install crewai-tokportal
# for the MCP variants:
pip install "crewai-tokportal[mcp]"     # == crewai-tools[mcp]
```

Get an API key at <https://app.tokportal.com/developer>:

```bash
export TOKPORTAL_API_KEY=sk_...
```

## Crew example (native tools)

```python
from crewai import Agent, Crew, Task

from crewai_tokportal import tokportal_tools

operator = Agent(
    role="TokPortal operator",
    goal="Order and schedule managed social accounts for the marketing team",
    backstory=(
        "You operate TokPortal, a managed social infrastructure API. You always check the "
        "credit balance first, create a bundle, configure its videos, then publish it so a "
        "human account manager can start."
    ),
    tools=tokportal_tools(),          # reads TOKPORTAL_API_KEY; or tokportal_tools("sk_...")
    llm="gpt-4.1",
    verbose=True,
)

order = Task(
    description=(
        "Order one new TikTok account in the US with 3 video slots and advanced warming on "
        "'home workout', 'protein snacks', 'gym motivation'. Publish the bundle and report "
        "its id and status."
    ),
    expected_output="The bundle id, its status, and the remaining credit balance.",
    agent=operator,
)

crew = Crew(agents=[operator], tasks=[order])
print(crew.kickoff())
```

Every tool returns a JSON string: the TokPortal `data` envelope, or
`{"error": {"status", "code", "message", "request_id", "retryable"}}` so the
agent can self-correct.

## Full MCP tool set

### Recommended: `Agent(mcps=[...])` (CrewAI ≥ 1.x)

```python
from crewai import Agent
from crewai_tokportal import tokportal_mcp_server

agent = Agent(
    role="TokPortal operator",
    goal="...",
    backstory="...",
    mcps=[tokportal_mcp_server()],   # MCPServerHTTP, streamable HTTP + Bearer auth
    llm="gpt-4.1",
)
```

`tokportal_mcp_server()` accepts `MCPServerHTTP` kwargs such as
`tool_filter=` or `cache_tools_list=True`.

### Legacy: `MCPServerAdapter` context manager

```python
from crewai import Agent
from crewai_tools import MCPServerAdapter
from crewai_tokportal import tokportal_mcp_adapter

with MCPServerAdapter(tokportal_mcp_adapter(), connect_timeout=60) as mcp_tools:
    agent = Agent(role="...", goal="...", backstory="...", tools=mcp_tools, llm="gpt-4.1")
    ...
```

`tokportal_mcp_adapter()` returns
`{"url": "https://app.tokportal.com/api/ext/mcp", "transport": "streamable-http", "headers": {"Authorization": "Bearer sk_..."}}`.

## Tool reference (native)

| Tool | REST operation |
|---|---|
| `tokportal_get_credit_balance` | `GET /credits/balance` |
| `tokportal_create_bundle` | `POST /bundles` |
| `tokportal_configure_bundle_video` | `PUT /bundles/{id}/videos/{position}` |
| `tokportal_publish_bundle` | `POST /bundles/{id}/publish` |
| `tokportal_get_bundle` | `GET /bundles/{id}` |
| `tokportal_list_accounts` | `GET /accounts` |

Individual classes are exported too (`TokPortalCreateBundle(api_key=...)`, …).

## Resources

- API docs: <https://developers.tokportal.com>
- OpenAPI: <https://developers.tokportal.com/openapi.json>
- MCP server: <https://developers.tokportal.com/mcp>
- Python SDK: <https://github.com/tokportal/tokportal-python>
- LangChain package: <https://github.com/tokportal/langchain-tokportal>
- Support: team@tokportal.com

## License

MIT
