Dirextalk Local MCP

简体中文

Local MCP server for Dirextalk chat workflows.

Install

npm install -g dirextalk-mcp

For local testing before publishing the package:

npm install -g .

Configuration

Set:

export DIREXTALK_DOMAIN="https://example.com"
export DIREXTALK_AGENT_TOKEN="<agent token>"
export DIREXTALK_AGENT_ROOM_ID="!agents:example.com"

DIREXTALK_DOMAIN must be the service origin. Do not include /_p2p or /_matrix.

The server uses only DIREXTALK_AGENT_TOKEN. It does not request, store, or expose Matrix access tokens.

DIREXTALK_AGENT_ROOM_ID is optional but recommended for reading the agents room. When set, list_messages uses it as the default room_id for agents-room context.

send_message is an owner-scoped MCP tool for sending messages to the owner's non-agent rooms. It never defaults to DIREXTALK_AGENT_ROOM_ID, and it rejects that room if passed explicitly. Agent-room replies should be sent by dirextalk-agent-gateway / dirextalk-connect through the gateway-marked path.

For multi-service or multi-node local setups, prefer a node-scoped credentials file generated by dirextalk-deployer:

export DIREXTALK_CREDENTIALS_FILE="$HOME/.dirextalk/nodes/im.example.com/credentials.json"
export DIREXTALK_AGENT_NODE_ID="codex-im-example"

When DIREXTALK_CREDENTIALS_FILE is set, the server reads dirextalk_domain, dirextalk_agent_token, dirextalk_agent_room_id, and dirextalk_agent_node_id from profiles.default. It also accepts the flat deployer credential shape with homeserver, agent_token, agent_room_id, and agent_node_id.

dirextalk-agent-gateway does not depend on this MCP server to send messages. The gateway calls /_p2p/command action mcp.messages.send directly with gateway markers; this package is only the active owner-scoped tool surface for MCP-capable agents.

MCP Server Command

dirextalk-mcp

Example MCP client configuration:

{
  "mcpServers": {
    "dirextalk": {
      "command": "dirextalk-mcp",
      "env": {
        "DIREXTALK_CREDENTIALS_FILE": "/home/me/.dirextalk/nodes/im.example.com/credentials.json",
        "DIREXTALK_AGENT_NODE_ID": "codex-im-example"
      }
    }
  }
}

Check local configuration without starting the stdio MCP transport:

dirextalk-mcp doctor --json

The doctor output redacts DIREXTALK_AGENT_TOKEN.

Local MCP Daemon

MCP hosts that need a stable local endpoint can use the service-scoped daemon. The daemon serves MCP over Streamable HTTP on localhost, while dirextalk-mcp proxy keeps a stdio-compatible entrypoint for clients that still launch MCP servers as child processes.

dirextalk-mcp daemon install \
  --service-name im.example.com \
  --credentials-file "$HOME/.dirextalk/nodes/im.example.com/credentials.json" \
  --node-id hermes-im-example \
  --host 127.0.0.1 \
  --port 19757

dirextalk-mcp daemon status --service-name im.example.com --json
dirextalk-mcp proxy --url http://127.0.0.1:19757/mcp

On Windows, daemon install registers a per-user logon task. On macOS it writes a LaunchAgent, and on Linux it uses a user systemd service when systemctl --user is available. The daemon stores service metadata under $HOME/.dirextalk/daemons/.

Tools

• list_contacts - list or search accepted Dirextalk contacts/friends; use returned contact room_id with ordinary message tools.
• search_rooms - search or list direct contacts, groups, and unified channels. Use returned room_id with list_messages, send_message, or list_channel_posts depending on the room workflow.
• send_message - send a plain text ordinary chat message as the portal owner to a non-agent direct, group, or channel room by room_id. It is not for channel posts/comments.
• list_messages - read ordinary chat history by room_id; may default to DIREXTALK_AGENT_ROOM_ID. Channel post/comment events are excluded. Supports stable newest-first pagination with RFC3339/RFC3339Nano UTC from_time / to_time, opaque cursor, and limit.
• list_room_members - list room members with full Matrix IDs, username localparts, domains, display names, avatars, memberships, roles, and string joined_at.
• list_channel_posts - read unified channel post summaries by channel room_id. Use this for post feeds, not ordinary channel chat. Each post includes created_at, comment_count, like_count, local favorite_count, and favorited_by_me.
• list_post_comments - read comment details for a channel post_id when comment content is needed. Supports the same RFC3339 UTC from_time / to_time, cursor, and limit pagination.
• comment_channel_post - publish a plain text comment to an existing channel post. Use send_message instead for ordinary channel chat.

All tool results are concise JSON text. Read responses use readable UTC fields such as created_at, last_message_at, and string joined_at. To fetch new content during pagination, start a fresh request without cursor; cursor pages continue the original snapshot.

Development

If Node.js 20+ is not on PATH in WSL/Linux, install or select any Node 20+ runtime first, then make sure node -v reports a supported version.

node -v

Then run:

npm test
npm run typecheck
npm run build
npm pack --dry-run

Local Docker E2E Tests

The normal unit suite does not require a Dirextalk backend:

npm test

After the backend implements the six mcp.* actions, run the local Docker e2e harness with:

export DIREXTALK_E2E=1
export DIREXTALK_DOMAIN="https://localhost:8448"
export DIREXTALK_AGENT_TOKEN="<agent token>"

npm run test:e2e:local

For self-signed local Docker certificates, run with NODE_TLS_REJECT_UNAUTHORIZED=0.

With only DIREXTALK_DOMAIN and DIREXTALK_AGENT_TOKEN, the e2e suite smoke-tests search_rooms. Set these optional fixture IDs to exercise the remaining tools:

export DIREXTALK_E2E_ROOM_ID="!room:dendrite-a:8448"
export DIREXTALK_E2E_CHANNEL_ROOM_ID="!channel:dendrite-a:8448"
export DIREXTALK_E2E_POST_ID="post_123"

DIREXTALK_E2E_ROOM_ID enables send_message and list_messages. DIREXTALK_E2E_CHANNEL_ROOM_ID enables list_channel_posts. DIREXTALK_E2E_POST_ID enables list_post_comments and comment_channel_post.

MCP SDK Package

The initial plan referenced @modelcontextprotocol/server. npm currently publishes that package only as 2.0.0-alpha.2. This package uses the stable official @modelcontextprotocol/sdk package instead, with imports from @modelcontextprotocol/sdk/server/mcp.js and @modelcontextprotocol/sdk/server/stdio.js.