# sociallens

sociallens talks to Rolli IQ's social-media search and analytics
API: keyword, user, and expert searches and the posts they find,
the topic tree, agent runs, agent schedules, integration setup,
and account usage. One binary serves a command-line interface and
a stdio MCP server.

An API token is required. Set `ROLLI_API_TOKEN` before use; when
it is missing or blank, every tool fails with an error before any
request is made. `ROLLI_USER_ID` is optional and defaults to
`rolli-mcp`; its value is sent with every request. The API base
URL can be overridden with `SOCIALENS_API_URL`; when it is not
set, calls go to `https://api.rolli.ai`.

One difference from the original server is worth knowing up
front: the original waits, polling until a search completes
(which can take up to ten minutes). sociallens makes a single
request per tool call and returns whatever status and results
the API reports at that moment; call the matching `get_*` tool
again to check on a search that is still running.

## Install

```bash
npx @reneturcios/sociallens get_usage
```

Or run the container image:

```bash
docker run -i ghcr.io/cloudcorprecords/sociallens
```

The container defaults to the MCP server (see below). Pass CLI
arguments to use it as a CLI instead.

## CLI

The subcommands mirror the MCP tool names:

```bash
export ROLLI_API_TOKEN=...

sociallens list_keyword_searches --status completed
sociallens keyword_search --query "electric vehicles" --platforms x,reddit
sociallens get_keyword_search --id ks1
sociallens get_keyword_search_posts --id ks1
sociallens list_user_searches
sociallens user_search --query "@someone"
sociallens list_expert_searches
sociallens expert_search --query "climate science"
sociallens get_topic_tree
sociallens list_agent_runs --status running
sociallens start_agent_run --agent-id ag1 --input "weekly roundup"
sociallens create_agent_schedule --agent-id ag1 --cron-expression "0 9 * * *" --name daily
sociallens pause_agent_schedule --id s1
sociallens list_agent_schedule_runs --id s1
sociallens get_integration_setup
sociallens update_integration_setup --platform slack --enabled true
sociallens get_usage

sociallens --version
```

Results print the upstream JSON payload. Exit codes: `0` on
success, `1` when a call fails (including a missing token or an
upstream API error), `2` for usage errors.

## MCP server

One bin serves both faces. The `mcp` subcommand starts a stdio
MCP server:

```bash
npx -y @reneturcios/sociallens mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "sociallens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/sociallens", "mcp"],
      "env": { "ROLLI_API_TOKEN": "..." }
    }
  }
}
```

### Tools

| Tool | Input | What it does |
| --- | --- | --- |
| `list_keyword_searches` | `status` (optional) | List keyword searches. |
| `keyword_search` | `query` (required), `platforms`, `start_date`, `end_date` | Start a keyword search. |
| `get_keyword_search` | `id` (required) | Get one keyword search. |
| `list_user_searches` | `status` (optional) | List user searches. |
| `user_search` | `query` (required), `platforms`, `start_date`, `end_date` | Start a user search. |
| `get_user_search` | `id` (required) | Get one user search. |
| `list_expert_searches` | `status` (optional) | List expert searches. |
| `expert_search` | `query` (required), `platforms`, `start_date`, `end_date` | Start an expert search. |
| `get_expert_search` | `id` (required) | Get one expert search. |
| `get_topic_tree` | (none) | Get the topic tree. |
| `get_keyword_search_posts` | `id` (required) | Get a keyword search's posts. |
| `get_user_search_posts` | `id` (required) | Get a user search's posts. |
| `list_agent_runs` | `status` (optional) | List agent runs. |
| `start_agent_run` | `agent_id` (required), `input` | Start an agent run. |
| `get_agent_run` | `id` (required) | Get one agent run. |
| `cancel_agent_run` | `id` (required) | Cancel an agent run. |
| `rerun_agent_run` | `id` (required) | Re-run an agent run. |
| `update_agent_run` | `id` (required), `name`, `status` | Update an agent run. |
| `delete_agent_run` | `id` (required) | Delete an agent run. |
| `list_agent_schedules` | `status` (optional) | List agent schedules. |
| `create_agent_schedule` | `agent_id`, `cron_expression` (both required), `name` | Create an agent schedule. |
| `get_agent_schedule` | `id` (required) | Get one agent schedule. |
| `update_agent_schedule` | `id` (required), `name`, `cron_expression`, `agent_id` | Update an agent schedule. |
| `delete_agent_schedule` | `id` (required) | Delete an agent schedule. |
| `pause_agent_schedule` | `id` (required) | Pause an agent schedule. |
| `resume_agent_schedule` | `id` (required) | Resume an agent schedule. |
| `list_agent_schedule_runs` | `id` (required), `status` | List a schedule's runs. |
| `get_integration_setup` | (none) | Get the integration setup. |
| `update_integration_setup` | `platform`, `webhook_url`, `enabled` | Update the integration setup. |
| `get_usage` | (none) | Get account usage. |

`platforms` is an array of platform names. Dates use
`YYYY-MM-DD` form as `start_date` / `end_date`.

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx
```

## License

MIT — see `LICENSE`.