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:

npm install plurk-mcp

For local verification from this repository:

npm install
npm run build

CLI Usage

Run MCP mode:

npx plurk-mcp

Run debug mode:

npx plurk-mcp-debug

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

npx plurk-mcp debug

Environment Variables

Optional:

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:

{
  "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:

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

{
  "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:

npm install

Build:

npm run build

Type-check:

npm run lint

Run tests:

npm test

Create a tarball for local install verification:

npm pack

Project Structure

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