> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wip.computer/llms.txt
> Use this file to discover all available pages before exploring further.

# X Platform

> X Platform API. Read posts, search tweets, post updates, upload media. Built on the official xdk TypeScript SDK.

# X Platform

Read posts, search tweets, post updates, upload media.

Built on the official [@xdevplatform/xdk](https://github.com/xdevplatform/xdk) TypeScript SDK (v0.4.0, MIT, zero transitive deps).

Four interfaces: CLI, Module, Connection Point, Skill.

## Install

Open your AI and say:

```
Clone wipcomputer/wip-xai-x and read the README and SKILL.md.
Then explain to me:
1. What is this tool?
2. What does it do?
3. What would it change or fix in our current system?

Then ask me if I have more questions, or if I want you to integrate it into our system.
```

Your AI will read the repo, explain the tool, and walk you through integration interactively.

### Authentication

The tool resolves credentials automatically:

1. **1Password** (preferred) ... vault "Agent Secrets", item "X Platform API"
2. **Environment variables** ... as a fallback

**Read-only** (fetch posts, search, user lookup):

```bash theme={null}
export X_BEARER_TOKEN="your-bearer-token"
```

**Read + Write** (post tweets, bookmarks, upload media):

```bash theme={null}
export X_API_KEY="your-api-key"
export X_API_SECRET="your-api-secret"
export X_ACCESS_TOKEN="your-access-token"
export X_ACCESS_TOKEN_SECRET="your-access-token-secret"
```

Get credentials at [https://developer.x.com/en/portal/dashboard](https://developer.x.com/en/portal/dashboard)

## Usage

### CLI

```bash theme={null}
# Sensor (read)
wip-xai-x fetch https://x.com/parkertoddbrooks/status/123456
wip-xai-x search "AI agents" --max=20
wip-xai-x bookmarks --max=10
wip-xai-x user parkertoddbrooks
wip-xai-x me

# Actuator (write)
wip-xai-x post "Hello from wip-xai-x"
wip-xai-x post "Replying!" --reply-to=123456
wip-xai-x post "Check this out" --media=photo.jpg
wip-xai-x delete 123456
wip-xai-x bookmark 123456
wip-xai-x upload photo.jpg
```

### As a Module

```javascript theme={null}
import { fetch_post, search_recent, post_tweet, get_bookmarks } from '@wipcomputer/wip-xai-x';

// Sensor: read
const post = await fetch_post({ id_or_url: 'https://x.com/user/status/123' });
console.log(post.data.text);

const results = await search_recent({ query: 'AI agents', max_results: 10 });
for (const tweet of results.data) {
  console.log(tweet.text);
}

const bookmarks = await get_bookmarks({ max_results: 20 });

// Actuator: write
const { data } = await post_tweet({ text: 'Hello from wip-xai-x' });
console.log(`Posted: https://x.com/i/status/${data.id}`);
```

### Connection Point

Add to your `.mcp.json`:

```json theme={null}
{
  "wip-xai-x": {
    "command": "node",
    "args": ["/path/to/wip-xai-x/mcp-server.mjs"]
  }
}
```

Exposes 7 tools: x\_fetch\_post, x\_search\_recent, x\_get\_bookmarks, x\_get\_user, x\_post\_tweet, x\_delete\_tweet, x\_upload\_media.

## Functions

### Sensor (Read)

| Function        | What                        | Auth   |
| --------------- | --------------------------- | ------ |
| `fetch_post`    | Fetch a post by ID or URL   | Bearer |
| `search_recent` | Search tweets (last 7 days) | Bearer |
| `get_bookmarks` | Get your bookmarks          | OAuth  |
| `get_user`      | Get user profile            | Bearer |
| `get_me`        | Get your own profile        | OAuth  |

### Actuator (Write)

| Function          | What                   | Auth  |
| ----------------- | ---------------------- | ----- |
| `post_tweet`      | Post a new tweet       | OAuth |
| `delete_tweet`    | Delete a tweet         | OAuth |
| `bookmark_post`   | Bookmark a post        | OAuth |
| `unbookmark_post` | Remove a bookmark      | OAuth |
| `upload_media`    | Upload image/video/gif | OAuth |

**Bearer** = read-only bearer token. **OAuth** = OAuth 1.0a with all four tokens.

## wip-xai-x vs wip-xai-grok

|                | wip-xai-x                     | wip-xai-grok               |
| -------------- | ----------------------------- | -------------------------- |
| **API**        | X Platform API (api.x.com)    | xAI API (api.x.ai)         |
| **Search**     | Raw tweet data, exact matches | AI-powered search via Grok |
| **Read posts** | Fetch by ID, search by query  | Not available              |
| **Write**      | Post tweets, upload media     | Generate images/video      |
| **Auth**       | Bearer token / OAuth 1.0a     | xAI API key                |

Use **wip-xai-x** to read/write on X. Use **wip-xai-grok** for AI-powered search and media generation.

## Attribution

Built on [@xdevplatform/xdk](https://github.com/xdevplatform/xdk) v0.4.0 (official X TypeScript SDK).

## License

MIT