# plurk-mcp

`plurk-mcp` is a guarded Plurk MCP execution layer for OpenClaw.

It is designed for MCP callers that may operate multiple Plurk accounts and gives an agent a narrow, controlled tool surface for:

- reading account, alert, mention, and thread context
- creating new plurks
- replying only to eligible interactions
- enforcing posting guardrails in the execution layer instead of trusting prompt behavior

This repository does not implement editorial strategy, scheduling logic, or campaign decisions. OpenClaw decides what to post and when to post it. `plurk-mcp` only reads context, executes approved actions, applies safeguards, and records local audit logs.

## Features

- npm-installable CLI package with dedicated `MCP` and `debug` entrypoints
- request-scoped Plurk credentials so each tool call can target a different account
- Plurk OAuth 1.0a request signing
- approved v1 tool surface only:
  - `plurk_get_me`
  - `plurk_get_alerts`
  - `plurk_get_mentions_context`
  - `plurk_get_thread_context`
  - `plurk_post`
  - `plurk_reply`
- server-side guardrails:
  - daily new-post limit
  - per-thread reply cooldown
  - reply eligibility checks
- local JSONL audit logs
- local-only web debug console

## Safety Model

This project is intentionally restrictive.

Allowed in v1:
- read profile, alerts, mentions context, and thread context
- create a new plurk
- reply to an explicit mention or a reply on a plurk authored by the operator account

Not exposed in v1:
- edit plurk
- delete plurk
- follow user
- fan-management actions
- unrelated public-thread participation

## Requirements

- Node.js `>= 22`
- a caller that can supply a Plurk application key, application secret, access token, and access token secret with each MCP tool call or debug action

## Install

If the package is published to npm:

```bash
npm install plurk-mcp
```

For local verification from this repository:

```bash
npm install
npm run build
```

## CLI Usage

Run MCP mode:

```bash
npx plurk-mcp
```

Run debug mode:

```bash
npx plurk-mcp-debug
```

You can also use the main binary with the `debug` subcommand:

```bash
npx plurk-mcp debug
```

## Environment Variables

Optional:

```bash
export PLURK_MCP_TIMEZONE="UTC"
export PLURK_MCP_DAILY_POST_LIMIT="10"
export PLURK_MCP_REPLY_COOLDOWN_MINUTES="15"
export PLURK_MCP_DEBUG_HOST="127.0.0.1"
export PLURK_MCP_DEBUG_PORT="3939"
export PLURK_MCP_DATA_DIR="./data"
```

Meaning of the optional values:

- `PLURK_MCP_TIMEZONE`
  Used for daily quota rollover and audit file partitioning.
- `PLURK_MCP_DAILY_POST_LIMIT`
  Maximum number of new plurks per local day. Replies do not consume this budget.
- `PLURK_MCP_REPLY_COOLDOWN_MINUTES`
  Minimum cooldown between automatic replies in the same thread.
- `PLURK_MCP_DEBUG_HOST`
  Debug server bind host. Defaults to `127.0.0.1`.
- `PLURK_MCP_DEBUG_PORT`
  Debug server port. Must be a positive integer.
- `PLURK_MCP_DATA_DIR`
  Root directory for audit logs and policy state.

## MCP Tools

Every supported MCP tool now requires a `credentials` object:

```json
{
  "credentials": {
    "appKey": "your-app-key",
    "appSecret": "your-app-secret",
    "accessToken": "your-access-token",
    "accessTokenSecret": "your-access-token-secret"
  }
}
```

This is a breaking change from the original env-bound single-account model.

### `plurk_get_me`

Returns the authenticated account profile for the credentials supplied in this call.

### `plurk_get_alerts`

Returns recent normalized alerts for the credentials supplied in this call.

### `plurk_get_mentions_context`

Returns recent mention-driven interactions suitable for summarization or reply planning for the credentials supplied in this call.

### `plurk_get_thread_context`

Returns the parent plurk plus normalized replies for a specific thread using the credentials supplied in this call.

### `plurk_post`

Creates a new plurk and consumes the daily new-post quota for the authenticated account tied to the supplied credentials.

### `plurk_reply`

Creates a reply only when:

- the thread belongs to a plurk authored by the operator account, or
- the interaction explicitly mentions the operator account

Replies outside that boundary are rejected before the server calls Plurk.

## Guardrails

The server enforces these rules regardless of what the agent asks it to do:

- new posts are limited to `10` per local day by default for each authenticated account
- replies do not consume the daily post budget for that account
- replies in the same thread are rate-limited with a default `15` minute cooldown for that account
- unsupported high-risk actions are not registered as tools
- policy denials and upstream failures are logged locally

## Debug Console

The debug console is local-only by default and is intended for operator testing, not public access.

It provides:

- sanitized runtime configuration summary
- manual credential inputs for app key, app secret, access token, and access token secret
- active-account summary for the credentials used by the latest successful action
- buttons and forms for approved v1 actions only
- normalized JSON responses
- policy-denial visibility
- recent audit log inspection

Credential-bearing debug actions use JSON `POST` bodies so secrets do not appear in query strings.

Default URL:

```text
http://127.0.0.1:3939
```

## Data Files

By default the server writes:

- `data/audit/YYYY-MM-DD.jsonl`
- `data/policy-state.json`

The audit log records:

- successful reads
- successful writes
- policy denials
- upstream failures
- authenticated account attribution when available

Secrets are intentionally excluded from the logged metadata.

## OpenClaw MCP Host Example

```json
{
  "mcpServers": {
    "plurk": {
      "command": "npx",
      "args": ["plurk-mcp"],
      "env": {
        "PLURK_MCP_TIMEZONE": "UTC",
        "PLURK_MCP_DAILY_POST_LIMIT": "10",
        "PLURK_MCP_REPLY_COOLDOWN_MINUTES": "15"
      }
    }
  }
}
```

Your MCP caller must now inject the Plurk credential bundle into each tool invocation instead of binding one account through process env vars.

## Development

Install dependencies:

```bash
npm install
```

Build:

```bash
npm run build
```

Type-check:

```bash
npm run lint
```

Run tests:

```bash
npm test
```

Create a tarball for local install verification:

```bash
npm pack
```

## Project Structure

```text
src/
  bin/                  CLI entrypoints
  config/               environment parsing and runtime config
  domain/               shared types and error helpers
  integrations/plurk/   OAuth signing, API calls, normalization
  services/             policy and application services
  storage/              audit and policy-state persistence
  transports/mcp/       MCP tool registration
  transports/debug/     local web debug console
test/                   automated tests
```

## Current Status

The package, CLI entrypoints, tests, and npm artifact verification are in place.

What still depends on your real environment:

- end-to-end verification against live Plurk credentials
- any tuning of rate limits or upstream response handling discovered during real usage