# langchain-tokportal

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

LangChain / LangGraph integration for **TokPortal**.

**TokPortal is the managed social infrastructure API: real TikTok and Instagram 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.**

This package gives your agents two ways to drive TokPortal:

| Mode | What you get | When to use |
|---|---|---|
| **Native tools** (`toolkit.get_tools()`) | 6 hand-written `BaseTool`s wrapping the [`tokportal`](https://pypi.org/project/tokportal/) Python SDK: credit balance, create bundle, configure video, publish bundle, get bundle, list accounts | Simple sync agents, no MCP dependency at runtime |
| **MCP tools** (`await toolkit.aget_tools("mcp")`) | Every tool of the remote TokPortal MCP server (90+ operations: uploads, warming, analytics, webhooks, comments, bans…) loaded through [`langchain-mcp-adapters`](https://github.com/langchain-ai/langchain-mcp-adapters) | Full API surface, async agents |

## Installation

```bash
pip install langchain-tokportal
# optional, for the LangGraph example below
pip install langchain langchain-openai
```

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

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

## Quick start (native tools)

```python
from langchain_tokportal import TokPortalToolkit

toolkit = TokPortalToolkit.from_api_key()          # reads TOKPORTAL_API_KEY
tools = toolkit.get_tools()

for tool in tools:
    print(tool.name)
# tokportal_get_credit_balance
# tokportal_create_bundle
# tokportal_configure_bundle_video
# tokportal_publish_bundle
# tokportal_get_bundle
# tokportal_list_accounts

print(tools[0].invoke({}))                          # -> {"data": {"balance": ...}}
```

Every tool returns a JSON string (the raw TokPortal `data` envelope, or an
`{"error": {...}}` object with `status`, `code`, `request_id` and `retryable`
so the model can self-correct).

## LangGraph agent example (`langchain.agents.create_agent`, LangChain 1.x)

```python
import asyncio

from langchain_openai import ChatOpenAI
from langchain.agents import create_agent

from langchain_tokportal import TokPortalToolkit

SYSTEM = (
    "You operate TokPortal, a managed social infrastructure API. "
    "Always check the credit balance before creating bundles. "
    "A bundle must be published for a human account manager to start working on it."
)


async def main() -> None:
    toolkit = TokPortalToolkit.from_api_key()

    # "native" = 6 SDK tools, "mcp" = full remote MCP tool set, "all" = both
    tools = await toolkit.aget_tools("mcp")

    agent = create_agent(ChatOpenAI(model="gpt-4.1"), tools, system_prompt=SYSTEM)

    result = await agent.ainvoke(
        {
            "messages": [
                (
                    "user",
                    "Order one new TikTok account in the US with 3 video slots and "
                    "advanced warming on the terms 'home workout', 'protein snacks', "
                    "'gym motivation'. Publish it and tell me the bundle id.",
                )
            ]
        }
    )
    print(result["messages"][-1].content)


asyncio.run(main())
```

Sync-only code paths can call `toolkit.get_mcp_tools()` (wraps `asyncio.run`).

## Using the MCP connection directly

```python
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_tokportal import mcp_connection

client = MultiServerMCPClient({"tokportal": mcp_connection("sk_...")})
tools = await client.get_tools()
```

`mcp_connection()` returns a Streamable-HTTP connection dict pointing at
`https://app.tokportal.com/api/ext/mcp` with `Authorization: Bearer <api_key>`.

## 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` |

Typical flow: `get_credit_balance` → `create_bundle` (draft) → `configure_bundle_video` × N → `publish_bundle` → poll `get_bundle` or subscribe to [webhooks](https://developers.tokportal.com/webhooks).

## Resources

- API docs: <https://developers.tokportal.com>
- OpenAPI: <https://developers.tokportal.com/openapi.json>
- MCP server: <https://developers.tokportal.com/mcp> (remote `https://app.tokportal.com/api/ext/mcp`, stdio `npx -y tokportal-mcp`)
- Python SDK: <https://github.com/tokportal/tokportal-python>
- Support: team@tokportal.com

## License

MIT