Claude-Code on Yarang's Tech Lair

Building a Blog AI Auto-Comment System (1/3) — Architecture and Implementation

Sun, 03 May 2026 01:00:00 +0900

Overview

I built a system where AI automatically responds to blog comments. When a reader leaves a comment on a blog post, the AI assistant analyzes the post context and automatically generates a technically accurate yet friendly reply.

This series consists of three parts:

Part 1 (This post): Overall architecture design and core code implementation
Part 2: File-based authentication, permission management, security hardening
Part 3: systemd deployment, nginx proxy, troubleshooting

System Architecture

Overall Data Flow

Reader writes a comment
 ↓
[giscus] → Creates a comment on GitHub Discussions
 ↓
[GitHub Webhook] → Sends HTTP POST
 ↓
[nginx reverse proxy] → Header forwarding
 ↓
[Flask Worker] → Signature verification → Comment analysis
 ↓
[Claude Code CLI] → Generates AI response
 ↓
[GitHub GraphQL API] → Posts reply to Discussion
 ↓
[giscus] → Displays reply on blog

The key point in this architecture is that giscus uses GitHub Discussions as a comment storage. Therefore, we can receive new comment events via GitHub Webhook and post responses using the same GitHub API.

Components

Component	Role	Technology
giscus	Blog comment widget	Based on GitHub Discussions
GitHub Webhook	Event delivery	`discussion_comment` event
nginx	Reverse proxy	Header forwarding, SSL termination
Flask Worker	Webhook receiving and processing	Python, Flask, Flask-Limiter
Claude Code	AI response generation	`--print` mode CLI call
GitHub GraphQL	Response posting	Mutation API

giscus Configuration

To integrate giscus into a Hugo blog, the following configuration is required in hugo.toml:

[params]
 [params.comments]
 enabled = true
 provider = "giscus"
 [params.comments.giscus]
 repo = "yarang/blogs"
 repoId = "YOUR_REPO_ID"
 category = "General"
 categoryId = "YOUR_CATEGORY_ID"
 mapping = "pathname"
 strict = "0"
 reactionsEnabled = "1"
 emitMetadata = "0"
 inputPosition = "bottom"
 lang = "ko"
 theme = "noborder_gray"

mapping = "pathname" maps Discussions based on the post URL path. This creates an independent Discussion for each blog post.

GitHub Webhook Configuration

In the GitHub repository Settings > Webhooks:

Payload URL: https://your-domain/webhook
Content type: application/json
Secret: Secret for HMAC-SHA256 signature (covered in detail in the security post)
Events: Select Discussion comments

The Webhook sends a discussion_comment event to the Flask worker whenever a comment is created.

Flask Worker Implementation

Project Structure

auto-comment-worker/
├── scripts/
│ └── auto-comment-worker.py # Main worker
├── deploy/
│ └── auto-comment-worker.service # systemd service
├── venv/ # Python virtual environment
└── logs/
 └── audit.log # Audit log

Core Dependencies

from flask import Flask, request, jsonify
from flask_limiter import Limiter
from flask_limiter.util import get_remote_address
from marshmallow import Schema, fields, validate, ValidationError

Flask: Provides Webhook endpoints as a lightweight web framework
Flask-Limiter: Prevents abuse with rate limiting (10 times per minute)
marshmallow: Safe data parsing via request schema validation

Webhook Endpoint

@app.route('/webhook', methods=['POST'])
@limiter.limit("10 per minute")
def github_webhook():
 """Receives GitHub Webhook"""
 # 1. Signature verification
 signature = request.headers.get('X-Hub-Signature-256')
 if not verify_webhook_signature(request.data, signature):
 log_audit('SIGNATURE_INVALID', {'ip': request.remote_addr})
 return jsonify({'status': 'unauthorized'}), 401

 # 2. Request schema validation
 schema = WebhookSchema()
 try:
 payload = schema.load(request.json)
 except ValidationError as err:
 return jsonify({'status': 'invalid'}), 400

 # 3. Extract and filter comment information
 comment = payload.get('comment', {})
 discussion = payload.get('discussion', {})
 original_author = comment.get('user', {}).get('login', 'User')

 # Ignore if it's the blog owner's comment
 if _is_blog_owner(original_author):
 return jsonify({'status': 'owner_comment_ignored'}), 200

 # Ignore if AI generated comment (prevent infinite loop)
 if _is_ai_generated_comment(comment.get('body', '')):
 return jsonify({'status': 'ai_comment_ignored'}), 200

 # 4. Generate and post AI response
 discussion_graphql_id = get_discussion_graphql_id(
 repo_owner, repo_name, discussion_number
 )
 context = f"Title: {discussion_title}\n\nContent: {discussion_body}"
 reply = analyze_comment(context, comment_body)
 post_reply_graphql(discussion_graphql_id, comment_body, original_author, reply)

The core flow consists of 4 steps:

Signature verification: Verifies if the request came from GitHub using HMAC-SHA256
Schema validation: Validates payload structure with marshmallow
Filtering: Ignores comments from the blog owner and the AI itself (prevents infinite loops)
Response: Generates AI response with Claude Code and posts via GraphQL API

Preventing Infinite Loops

If AI responds to a comment created by AI, it will fall into an infinite loop. To prevent this, we use marker-based detection:

def _is_ai_generated_comment(body: str) -> bool:
 """Identifies if the comment was generated by AI"""
 ai_markers = [
 '🤖 AI Assistant',
 'AI Assistant',
 'AgentForge',
 'Automatically generated by Claude Code',
 'was automatically generated'
 ]
 body_lower = body.lower()
 return any(marker.lower() in body_lower for marker in ai_markers)

When posting the AI response, you must include one of these markers in the body:

body = f"""---
**🤖 AI Assistant**

{safe_reply}

*This comment was automatically generated by AgentForge + Claude Code.*
---
"""

Calling Claude Code CLI

Use Claude Code’s --print mode to generate an AI response non-interactively:

def analyze_comment(context: str, comment: str) -> str:
 """Run Claude Code with AgentForge settings"""
 prompt = f"""## Blog Post Context
{context[:2000]}

## Reader Comment
{comment}

Please write a response to this comment.
- As a technical blog assistant, be professional yet friendly
- Concise within 200 characters
- Provide additional info or links if needed
"""

 cmd = [
 CLAUDE_CODE_PATH,
 '--settings', AGENTFORGE_CONFIG,
 '--print', prompt
 ]

 result = run(cmd, capture_output=True, text=True, timeout=60)

 if result.returncode == 0 and result.stdout.strip():
 return result.stdout.strip()

 return "Thanks for your opinion! I think it would be great to discuss the technical aspects further. 🙏"

Specify the AgentForge dedicated configuration file with the --settings flag. You can manage the model, token limits, etc. in this configuration file.

The --print flag runs Claude Code in non-interactive mode and outputs the result to stdout. Unlike interactive mode, it terminates after a single prompt-response.

GitHub GraphQL API Integration

Since giscus uses GitHub Discussions, the response must also be posted via the GitHub GraphQL API.

Retrieve Discussion GraphQL ID:

def get_discussion_graphql_id(repo_owner, repo_name, discussion_number):
 query = """
 query($owner: String!, $name: String!, $number: Int!) {
 repository(owner: $owner, name: $name) {
 discussion(number: $number) {
 id
 }
 }
 }
 """
 variables = {
 "owner": repo_owner,
 "name": repo_name,
 "number": discussion_number
 }

 response = requests.post(
 GITHUB_API_URL,
 json={"query": query, "variables": variables},
 headers={
 "Authorization": f"Bearer {GITHUB_TOKEN}",
 "Content-Type": "application/json"
 },
 timeout=10
 )

 if response.status_code == 200:
 data = response.json()
 return data["data"]["repository"]["discussion"]["id"]
 return None

The Webhook payload only includes the Discussion’s REST API ID. However, to post a comment, the GraphQL Node ID is required. Therefore, we first retrieve the Discussion’s Node ID via a GraphQL query, then use it to post the comment.

Post Response (Mutation):

def post_reply_graphql(discussion_graphql_id, original_comment, original_author, reply):
 query = """
 mutation($discussionId: ID!, $body: String!) {
 addDiscussionComment(input: {
 discussionId: $discussionId, body: $body
 }) {
 comment { id, databaseId }
 }
 }
 """
 # ... (Send request)

The addDiscussionComment mutation adds a new comment to the entire Discussion. It is a Discussion-level comment, not a reply to a specific comment.

Input Sanitization

Since user comments are external input, they must be sanitized:

def sanitize_comment(body: str) -> str:
 """User input sanitization"""
 if not body:
 return body
 body = re.sub(r'<[^>]+>', '', body) # Remove HTML tags
 body = html.escape(body) # Escape HTML entities
 body = body[:1000] # Length limit
 return body

To prevent XSS attacks, HTML tags are removed, remaining special characters are escaped, and the length is limited to 1000 characters.

Audit Logging

We keep audit logs to track security events:

def log_audit(event_type: str, details: dict):
 """Record security event audit log"""
 with open(AUDIT_LOG, 'a') as f:
 f.write(json.dumps({
 'timestamp': datetime.utcnow().isoformat(),
 'event': event_type,
 'details': details
 }) + '\n')

Event types recorded:

SIGNATURE_INVALID: Webhook signature verification failed
INVALID_PAYLOAD: Invalid request payload
WEBHOOK_RECEIVED: Webhook received successfully
AI_RESPONSE_SENT: AI response posted successfully

Conclusion

In this Part 1, we covered the overall architecture and core implementation code connecting giscus, GitHub Webhook, Flask worker, Claude Code CLI, and GitHub GraphQL API.

In the upcoming Part 2, we will cover security hardening for this system — file-based authentication management, file permission verification, HMAC-SHA256 signature verification, and more in detail.

This post is Part 1 of the AgentForge blog automatic comment system series.

Claude Code Discord MCP Plugin - Fixing asdf bun Path Issue

Thu, 26 Mar 2026 00:00:00 +0900

Problem

When installing the discord plugin for Discord channel integration in Claude Code CLI, I encountered the following error:

> discord Plugin · claude-plugins-official · √ enabled
 └ discord MCP · × failed

The plugin was enabled, but the MCP server was in a failed state.

Root Cause

This issue occurs when using bun installed via asdf. Claude Code CLI looks for the bun command to run the MCP server, but asdf uses shell wrappers, so the actual binary cannot be found in the system-wide path.

Solution

I resolved this by entering the absolute path to the bun installed via asdf.

Finding the Absolute Path of asdf-installed bun

which bun

Or:

asdf where bun

Example output:

/Users/yarang/.asdf/installs/bun/1.x.x/bin/bun

Applying the Configuration

Specify this absolute path as the execution path in the Discord MCP configuration, and the problem will be resolved.

Summary

Situation	Solution
System-wide installed bun	Use `bun` command
asdf-installed bun	Enter absolute path directly

When using asdf, you must specify the actual binary path, not the shell wrapper, for the MCP server to run properly.

References

Claude Code Plugin Development Complete Guide — From plugin.json to Deployment

Mon, 23 Mar 2026 10:53:23 +0900

# Claude Code Plugin Development Complete Guide — From plugin.json to Deployment

Claude Code CLI officially supports the **plugin system** starting from `v2.1.0`. By combining four components—skills, agents, commands, and hooks—you can package Claude's behavior like a tool and deploy it across your team. Based on the actual operational `yarang-plugins` marketplace repo, this article explains step-by-step so that developers creating a plugin for the first time can make it all the way to deployment.

---

## What is a Plugin? — The 4 Components of Claude Code Extensions

Claude Code plugins are not just simple script bundles. By combining the following four elements, you declaratively define Claude's roles and behaviors.

| Component | Directory | Role |
|---|---|---|
| **skills** | `skills/<name>/SKILL.md` | Inject specific domain knowledge and behavioral rules into Claude |
| **agents** | `agents/<role>.md` | Define sub-agent personas (assign expert roles) |
| **commands** | `commands/<verb>-<noun>.md` | Register /slash-command shortcuts |
| **hooks** | `hooks/hooks.json` | Automatic execution triggers before/after tool calls |

```mermaid
graph TD
 A[User Request] --> B[Command /create-post]
 B --> C[Load Skill blog-writer]
 C --> D[Execute Claude Writing]
 D --> E{Call Write Tool}
 E --> F[Execute Hook PostToolUse]
 F --> G[Automatic SEO Review]
 G --> H[Final Output]

Step 1: Create Directory Structure

Plugin names must be written in kebab-case in the format <domain>-<function>. Examples: blog-writer, domain-checker.

plugins/blog-writer/
├── .claude-plugin/
│ └── plugin.json ← Plugin metadata (required)
├── skills/
│ └── blog-writer/
│ └── SKILL.md ← Skill file name is fixed as SKILL.md
├── agents/
│ └── editor.md ← <role>.md format
├── commands/
│ └── create-post.md ← <verb>-<noun>.md format
├── hooks/
│ └── hooks.json ← hooks are only declared here
└── README.md

If you violate the file naming conventions, Claude Code will not recognize the file.

Step 2: Write plugin.json — Core of Metadata

plugin.json is the plugin’s ID card. If you specify only the directory paths in the skills, commands, and agents fields, it automatically explores the internal files.

{
 "name": "blog-writer",
 "description": "A skill plugin that structurally writes SEO-optimized blog posts",
 "author": {
 "name": "yarang",
 "url": "https://github.com/yarang"
 },
 "license": "MIT",
 "keywords": ["blog", "seo", "writing", "content"],
 "skills": "./skills/",
 "commands": "./commands/"
}

3 Important Notes:

Do not include the version field in plugin.json — Internal plugins only declare versions in marketplace.json.
Do not specify the hooks field here — v2.1+ automatically detects hooks/hooks.json.
Referencing paths outside the plugin directory using ../ is prohibited.

Step 3: Write SKILL.md — Inject Claude’s Expertise

A skill is a markdown document that injects behavioral rules and knowledge of a specific domain into Claude. Let’s look at the SKILL.md of the blog-writer plugin as an example.

# Blog Writer Skill

Writes an SEO-optimized blog post on a given topic.

## Structure

1. **Title (H1)**: Includes keywords, encourages clicks
2. **Introduction**: Raise reader's problem, introduce content covered
3. **Body**: Structured with H2/H3 subheadings, naturally includes core keywords
4. **Conclusion**: Core summary, Call to Action (CTA)

## Guidelines

- Sentences should be clear
- Write sufficient explanations in paragraphs
- Include keywords readers search for in the title and first paragraph
- Focus on practical information
- Also include diagrams

SKILL.md is injected like a system prompt when Claude is called with that skill. The more specific the behavioral guidelines, the higher the output quality.

Step 4: agents/ — Define Expert Sub-Agents

Agent files assign personas to Claude Code’s sub-agents. The name and description in the YAML frontmatter are key.

---
name: blog-editor
description: |
 Expert agent for blog editing.
 Reviews writing style, structure, and SEO optimization, and suggests improvements.
 When to use: When requesting review, editing, or proofreading of text.
---

# Technical Blog Editor Agent

You are a professional technical blog editor. Review articles based on the following criteria:

- Visualize operation methods with Mermaid diagrams
- Check SEO keyword density
- Verify inclusion of references

If you specify “When to use” in the description, Claude automatically selects that agent at the appropriate time.

Step 5: commands/ — Register Slash Commands

Command files register slash commands like /blog-writer:create-post. You can restrict allowed tools and descriptions via frontmatter.

---
description: Generate an SEO-optimized blog post
allowed-tools: Read, Write, WebFetch
---

# /blog-writer:create-post

Receives a topic from $ARGUMENTS and writes an SEO-optimized blog post.

If there is no topic, ask the user for one.

Use the blog-writer skill to write the post, and after completion, confirm whether to save it as a file.

$ARGUMENTS: Automatically binds arguments following the command. Use like /create-post AI agent design.
allowed-tools: Explicitly limits the tools the command can use for security.

Step 6: hooks/hooks.json — Set Automatic Triggers

Hooks define prompts or commands that Claude automatically executes before or after specific tool calls.

{
 "hooks": {
 "PostToolUse": [
 {
 "matcher": "Write",
 "hooks": [
 {
 "type": "prompt",
 "prompt": "Check the written file and review the title and first paragraph from an SEO perspective."
 }
 ]
 }
 ]
 }
}

This is an example of automatically triggering an SEO review immediately after the Write tool is executed. Hook events support PreToolUse, PostToolUse, Notification, Stop, etc.

sequenceDiagram
 participant U as User
 participant C as Claude
 participant H as Hook Engine

 U->>C: Execute /create-post
 C->>C: Call Write Tool
 C->>H: PostToolUse Event Fired
 H->>C: Inject SEO Review Prompt
 C->>U: Return SEO Review Result

Do not declare the hooks field in plugin.json. It is automatically recognized if only the hooks/hooks.json file exists (v2.1.0+).

Step 7: Register Plugin in marketplace.json

Internal plugins are registered in the marketplace root’s .claude-plugin/marketplace.json. The version is declared only here.

{
 "name": "yarang-plugins",
 "plugins": [
 {
 "name": "blog-writer",
 "description": "A skill plugin that structurally writes SEO-optimized blog posts",
 "version": "1.1.0",
 "keywords": ["blog", "seo", "writing", "content"],
 "source": {
 "source": "relative",
 "path": "./plugins/blog-writer"
 }
 },
 {
 "name": "domain-checker",
 "description": "Check domain availability",
 "keywords": ["domain", "rdap", "whois"],
 "source": {
 "source": "github",
 "repo": "yarang/skill-domain-checker",
 "ref": "v1.2.0"
 }
 }
 ]
}

For external repo plugins, set source.source to "github" and specify repo and ref (tag/branch).

Local Test → Deployment Workflow

flowchart LR
 A[Write Plugin] --> B[Local Test]
 B --> C{Check Behavior}
 C -- Failure --> A
 C -- Success --> D[Register in marketplace.json]
 D --> E[GitHub push]
 E --> F[Team Member Install]

# 1. Local Test (check immediately without installation)
claude --plugin-dir ./plugins/blog-writer

# 2. Refresh marketplace catalog
claude plugin marketplace update

# 3. Personal Install (user scope, default)
claude plugin install blog-writer@yarang-plugins

# 4. Team Shared Install (project scope — recorded in .claude/settings.json)
claude plugin install blog-writer@yarang-plugins --scope project

Common Mistakes Checklist

Item	Correct Method
Skill file name	`SKILL.md` (fixed uppercase)
Command file name	`<verb>-<noun>.md` (e.g., `create-post.md`)
Agent file name	`<role>.md` (e.g., `editor.md`)
version location	Internal plugin → only `marketplace.json` / External plugin → only `plugin.json`
hooks location	`hooks/hooks.json` (not in plugin.json)
Path Escaping	Using `../` is prohibited

Conclusion

Claude Code plugins are a powerful system that packages Claude’s behavior using declarative markdown. Define metadata with plugin.json, inject expertise with SKILL.md, create shortcuts with commands/, and set automation triggers with hooks/hooks.json — so the entire team can share the same workflow.

To get started right now:

Create a plugins/<name>/ directory
Write plugin.json and SKILL.md
Run a local test with claude --plugin-dir ./plugins/<name>.

A single plugin automates dozens of repetitive team tasks.

References

Claude Code Plugin System Docs
yarang/yarang-plugins — CLAUDE.md, docs/PLUGIN_SPEC.md
Claude Code v2.1 Release Notes

[Discord Decision MCP] Architecture Design Document

Mon, 02 Mar 2026 21:36:30 +0900

Discord Decision MCP — Architecture Design Document

1. Project Overview

1.1 Purpose

An MCP (Model Context Protocol) server that allows Claude Code, while operating in tmux Teammate mode for autonomous work, to ask questions via Discord when user decisions are needed and resume work after receiving responses.

1.2 Key Features

Feature	Description
One Bot per Project	Each project uses an independent Discord Bot
Infinite Wait Default	Wait for user response without timeout (Claude must not proceed unilaterally)
State Persistence	Restore waiting state after process restart
Korean-Friendly	Korean options, Yes/No response support
MCP-Based Communication	All Discord communication through MCP Tools

1.3 Version Information

Version: 1.0.0
Python Requirement: >= 3.11
MCP Framework: FastMCP >= 0.1.0

2. Directory Structure

discord-decision/
├── discord_mcp/ # Main package
│ ├── __init__.py
│ ├── server.py # MCP server entry point
│ ├── config.py # Environment variable configuration
│ │
│ ├── bot/ # Discord API client
│ │ ├── __init__.py
│ │ ├── client.py # REST API client (httpx)
│ │ └── gateway.py # WebSocket gateway (receive only)
│ │
│ ├── decision/ # Decision request management
│ │ ├── __init__.py
│ │ ├── manager.py # Decision request lifecycle management
│ │ ├── poller.py # Discord polling and response waiting
│ │ ├── parser.py # User response parsing
│ │ └── state.py # State persistence (JSON files)
│ │
│ ├── tools/ # MCP Tools implementation
│ │ ├── __init__.py
│ │ ├── ask.py # discord_ask_decision
│ │ ├── notify.py # discord_notify
│ │ ├── report.py # discord_report_progress
│ │ ├── status.py # discord_check_pending
│ │ ├── inbox.py # discord_read_inbox, discord_clear_inbox
│ │ └── _templates.py # Discord message templates
│ │
│ └── daemon/ # Watcher daemon
│ ├── __init__.py
│ ├── watcher.py # Discord channel monitoring (discord-watch CLI)
│ └── inbox.py # Inbox file management
│
├── scripts/ # Utility scripts
│ └── start-discord-watch.sh
│
├── tests/ # Test suite
│ ├── __init__.py
│ ├── test_parser.py
│ └── test_state.py
│
├── CLAUDE.md # Claude Code project instructions
├── README.md # Project description
├── pyproject.toml # Project configuration and dependencies
└── mcp.json.example # MCP configuration example

3. Key Module Descriptions

3.1 Server Entry Point (`server.py`)

Role: FastMCP server creation and MCP Tool registration

mcp = FastMCP(name="discord-decision-mcp")
# Tool registration
mcp.tool()(discord_ask_decision)
mcp.tool()(discord_notify)
mcp.tool()(discord_report_progress)
mcp.tool()(discord_check_pending)
mcp.tool()(discord_read_inbox)
mcp.tool()(discord_clear_inbox)

Execution:

discord-mcp # or python -m discord_mcp.server

3.2 Configuration Management (`config.py`)

Role: Load configuration values from environment variables

Environment Variable	Description	Default
`DISCORD_BOT_TOKEN`	Discord Bot Token (includes “Bot " prefix)	Required
`DISCORD_CHANNEL_ID`	Default question channel ID	Required
`PROJECT_NAME`	Used for question_id generation	“project”
`PENDING_DIR`	State file storage path	`~/.claude/pending_decisions`
`POLL_INTERVAL_SECONDS`	Discord polling interval (seconds)	5

3.3 Discord API Client (`bot/`)

3.3.1 REST API Client (`client.py`)

Role: Discord REST API calls (httpx-based)

Key Methods:

class DiscordClient:
 async def send_message(channel_id, content, embeds=None)
 async def get_messages(channel_id, after=None, limit=50)
 async def create_thread(channel_id, name, first_message)
 async def archive_thread(thread_id)

Features:

Automatic rate limit handling (retry on 429 response)
Singleton pattern (get_client())

3.3.2 WebSocket Gateway (`gateway.py`)

Role: Discord Gateway WebSocket connection (receive only)

Features:

Real-time MESSAGE_CREATE event reception
Reduces polling delay from 5 seconds to instant
System works without Gateway (polling fallback)
Automatic reconnection (Exponential backoff)

class GatewayClient:
 async def run() # Start event reception
 async def stop() # Close connection

3.4 Decision Request Management (`decision/`)

3.4.1 DecisionManager (`manager.py`)

Role: Coordinate the entire lifecycle of decision requests

class DecisionManager:
 async def ask(question, context, options, timeout_seconds, thread_id) -> PollResult
 async def restore_pending() -> list[DecisionState]

Flow:

Check for duplicate questions
Create thread (or reuse existing thread)
Create state file (~/.claude/pending_decisions/{question_id}.json)
Run poller to wait for response
Mark disconnected state on SIGHUP signal

3.4.2 DecisionPoller (`poller.py`)

Role: Poll Discord channel and wait for response

class DecisionPoller:
 async def wait(state: DecisionState) -> PollResult

Features:

Default: infinite wait (timeout_seconds=None)
Real-time waiting status display in tmux pane (ANSI escape)
Re-question up to 2 times for ambiguous responses

3.4.3 Response Parser (`parser.py`)

Role: Parse user Discord responses

Supported Patterns:

Option matching: “A”, “a”, “A번”, “A로 해줘”, “1”, “1번”
Affirmative/Negative: “yes”, “네”, “예”, “no”, “아니요”
Natural language: 15+ characters or 3+ Korean characters

def parse_response(text: str, options: list[str]) -> ParseResult
def build_clarify_message(...) -> str # Generate re-question message

3.4.4 State Store (`state.py`)

Role: Persist decision request state to JSON files

State File Location: ~/.claude/pending_decisions/{question_id}.json

class DecisionState(BaseModel):
 question_id: str
 project: str
 question: str
 context: str
 options: list[str]
 timeout_seconds: float | None
 thread_id: str
 message_id: str
 asked_at: str
 status: Literal["pending", "disconnected", "resolved", "aborted", "timeout"]
 clarify_attempts: int
 resolved_at: str | None
 resolution: str | None
 selected_option: str | None

class StateStore:
 def save(state: DecisionState)
 def load(question_id: str) -> DecisionState | None
 def load_all_pending() -> list[DecisionState]
 def resolve(question_id, resolution, selected_option)
 def is_duplicate(question: str) -> bool

3.5 MCP Tools (`tools/`)

Tool	Blocking	Description
`discord_ask_decision`	✅	User decision request
`discord_notify`	❌	Progress notification
`discord_report_progress`	❌	Task completion report
`discord_check_pending`	❌	Check pending questions
`discord_read_inbox`	❌	Inbox message query
`discord_clear_inbox`	❌	Inbox message deletion

3.6 Watcher Daemon (`daemon/`)

3.6.1 DiscordWatcher (`watcher.py`)

Role: Monitor Discord channel and record new messages to inbox file

Execution:

discord-watch --interval 10
# or
tmux new-session -d -s discord-watch 'uv run discord-watch'

Features:

Periodically poll specified channel(s)
Record new user messages to inbox
Display status in tmux pane

3.6.2 InboxStore (`inbox.py`)

Role: JSON file-based storage for Discord messages

Inbox File Location: ~/.claude/discord_inbox.json

class InboxMessage:
 message_id: str
 channel_id: str
 thread_id: str | None
 author: str
 author_id: str
 content: str
 timestamp: str
 read: bool

class InboxStore:
 def add_message(msg: InboxMessage)
 def get_unread() -> list[InboxMessage]
 def mark_read(message_id: str)
 def clear_read() # Delete read messages

4. Data Flow Diagrams

4.1 Decision Request Flow

┌─────────────────┐
│ Claude Code │
└────────┬────────┘
 │ discord_ask_decision()
 ▼
┌─────────────────────────────────────┐
│ MCP Server (server.py) │
│ ┌───────────────────────────────┐ │
│ │ DecisionManager.ask() │ │
│ │ 1. Duplicate check │ │
│ │ 2. Thread creation │ │
│ │ 3. State file save │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 ▼
┌─────────────────────────────────────┐
│ DecisionPoller.wait() │
│ ┌───────────────────────────────┐ │
│ │ Polling loop │ │
│ │ 1. tmux status update │ │
│ │ 2. Discord API call │ │
│ │ 3. Response parsing │ │
│ │ 4. Re-question if ambiguous │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 │
 ┌─────────┴─────────┐
 ▼ ▼
┌───────────────────┐ ┌──────────────────┐
│ Discord REST API │ │ Discord Thread │
│ (client.py) │ │ │
└───────────────────┘ └────────┬─────────┘
 │
 ┌────────▼────────┐
 │ User Response │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ parser.py │
 │ - Option match │
 │ - Ambiguity │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ store.resolve()│
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ PollResult │
 │ Return │
 └─────────────────┘

4.2 Watcher Daemon Flow

┌─────────────────────────────────────────────┐
│ DiscordWatcher (daemon/watcher.py) │
│ ┌───────────────────────────────────────┐ │
│ │ 1. Set initial message ID │ │
│ │ 2. Periodic polling (default 10s) │ │
│ │ 3. Detect new messages │ │
│ │ 4. InboxStore.add_message() │ │
│ └───────────────────┬───────────────────┘ │
└──────────────────────┼──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ ~/.claude/discord_inbox.json │
│ { │
│ "last_message_id": "...", │
│ "messages": [ │
│ { "message_id": "...", ... } │
│ ] │
│ } │
└──────────────────────┬──────────────────────┘
 ▲
 │ discord_read_inbox()
┌──────────────────────┴──────────────────────┐
│ Claude Code │
└─────────────────────────────────────────────┘

4.3 Session Restoration Flow

┌─────────────────────────────────────────────┐
│ Claude Code session start │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ discord_check_pending() │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ DecisionManager.restore_pending() │
│ ┌───────────────────────────────────────┐ │
│ │ 1. ~/.claude/pending_decisions/*.json │ │
│ │ 2. Check Thread via Discord API │ │
│ │ 3. If answered → Auto-resolve │ │
│ │ 4. If no answer → Restart notification│ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

5. MCP Tools List

5.1 discord_ask_decision

Description: Send question to Discord Thread and wait for response when user decision is needed (blocking)

Parameters:

Name	Type	Required	Description
`question`	string	✅	Question content
`context`	string	✅	Current work context
`options`	string[]	❌	List of options (empty array for free response)
`timeout_seconds`	float	❌	Wait timeout (null for infinite wait)
`thread_id`	string	❌	Existing Thread ID (null to create new Thread)

Return Value:

{
 "success": true,
 "answer": "A) Execute now",
 "selected_option": "A) Execute now",
 "question_id": "project_20260301_abc123",
 "timed_out": false,
 "aborted": false
}

5.2 discord_notify

Description: Send progress notification to Discord (non-blocking)

Parameters:

Name	Type	Required	Description
`message`	string	✅	Notification message
`level`	string	❌	info/warning/success/error (default: info)
`thread_id`	string	❌	Thread ID to send to (null for default channel)

5.3 discord_report_progress

Description: Report task completion or milestone completion (non-blocking)

Parameters:

Name	Type	Required	Description
`title`	string	✅	Report title
`summary`	string	✅	Task result summary
`details`	string[]	❌	List of detail items
`thread_id`	string	❌	Thread ID to send to

5.4 discord_check_pending

Description: Check pending questions at session start (non-blocking)

Parameters: None

Return Value:

{
 "has_pending": true,
 "pending_questions": [
 {
 "question_id": "project_20260301_abc123",
 "question": "Deploy?",
 "thread_id": "1234567890",
 "asked_at": "2026-03-01T10:30:00Z",
 "status": "pending"
 }
 ]
}

5.5 discord_read_inbox

Description: Query messages stored in Inbox (non-blocking)

Parameters:

Name	Type	Default	Description
`unread_only`	boolean	true	Return only unread messages
`mark_read`	boolean	false	Mark queried messages as read

5.6 discord_clear_inbox

Description: Delete Inbox messages (non-blocking)

Parameters:

Name	Type	Default	Description
`read_only`	boolean	true	Delete only read messages

6. Dependency Information

6.1 Core Dependencies

Package	Version	Purpose
`fastmcp`	>= 0.1.0	MCP server framework
`httpx`	>= 0.27.0	Async HTTP client
`websockets`	>= 12.0	WebSocket client
`python-dotenv`	>= 1.0.0	Environment variable loading
`pydantic`	>= 2.0.0	Data model validation
`anyio`	>= 4.0.0	Async execution

6.2 Development Dependencies

Package	Purpose
`pytest`	Test framework
`pytest-asyncio`	Async test support
`pytest-mock`	Mock support
`respx`	httpx mocking

6.3 CLI Commands

discord-mcp # Run MCP server
discord-watch # Run watcher daemon

7. State File Format

7.1 Decision State File

Location: ~/.claude/pending_decisions/{question_id}.json

{
 "question_id": "project_20260301_abc123",
 "project": "my-project",
 "question": "Run DB migration?",
 "context": "v1→v2 schema change",
 "options": ["A) Execute now", "B) Staging first", "C) Hold"],
 "timeout_seconds": null,
 "thread_id": "1234567890",
 "message_id": "0987654321",
 "asked_at": "2026-03-01T10:30:00Z",
 "status": "pending",
 "clarify_attempts": 0,
 "resolved_at": null,
 "resolution": null,
 "selected_option": null
}

7.2 Inbox File

Location: ~/.claude/discord_inbox.json

{
 "last_message_id": "1234567890",
 "messages": [
 {
 "message_id": "1234567890",
 "channel_id": "1234567890",
 "thread_id": null,
 "author": "username",
 "author_id": "1234567890",
 "content": "Message content",
 "timestamp": "2026-03-01T00:00:00Z",
 "read": false
 }
 ]
}

8. Architecture Principles

8.1 Design Principles

Singleton Pattern: DiscordClient, StateStore, InboxStore are module-level singletons
State Persistence: All decision request states are persisted to files
Infinite Wait Default: Timeout default is None so Claude does not proceed unilaterally
Re-question Limit: Ambiguous responses are re-asked up to 2 times
Rate Limit Handling: Automatic wait and retry on Discord API 429 responses

8.2 Error Handling

Situation	Handling
Discord API 429	Automatic wait and retry (max 5 times)
WebSocket disconnection	Reconnect with exponential backoff
Response parsing failure	Re-question up to 2 times then abort
Timeout occurrence	Send abort notification and set aborted state
Session disconnect (SIGHUP)	Save as disconnected state

Document Version: 1.0.0 Last Modified: 2026-03-02

Korean Version: 한국어 버전

[Discord MCP] Gateway Architecture Design

Sun, 01 Mar 2026 01:13:00 +0900

The Claude Code team designed a Discord Gateway Service for user communication via Discord. This article summarizes the key architecture decisions and user_comm Agent design.

1. Overall Architecture

Components

Layer	Component	Role
Discord	Bot, Channel, Thread	User interface
Gateway	WebSocket, REST API, SSE	Message routing
MCP	gcp-mcp, oci-mcp, db-mcp	Tool execution
user_comm	Discord Agent	User communication

Message Flow

flowchart LR
 subgraph D[Discord]
 U[User]
 end
 subgraph G[Gateway :8081]
 WS[WebSocket]
 API[REST API]
 SSE[SSE]
 end
 subgraph A[Claude Code Team]
 UC[user_comm]
 GCP[gcp-mcp]
 OCI[oci-mcp]
 DB[db-mcp]
 end

 U --> WS
 WS --> UC
 UC --> API
 API --> GCP
 API --> OCI
 API --> DB
 GCP --> UC
 OCI --> UC
 DB --> UC
 UC --> SSE
 SSE --> U

2. user_comm Agent (User Communication Handler)

Role and Responsibilities

The user_comm Agent is a member of the Claude Code team, communicating with users through Discord channels and collaborating with other agents.

Function	Description
Input Reception	Receive Discord messages and route to appropriate agent
Opinion Request	Query user opinions at other agents’ requests
Notification/Report	Send system status, warnings, reports
Team Communication	Exchange messages with other agents

Internal Structure

flowchart TB
 subgraph UC[user_comm Agent]
 DBot[Discord Bot]
 Agent[UserCommAgent]
 TComm[TeamCommunicator]
 DBot <--> Agent
 Agent <--> TComm
 end
 subgraph DAPI[Discord API]
 M[Messages]
 B[Buttons]
 T[Threads]
 end
 subgraph O[Other Agents]
 GCP[gcp-mcp]
 OCI[oci-mcp]
 AL[alert-mcp]
 end

 DBot <--> M
 DBot <--> B
 DBot <--> T
 TComm --> GCP
 TComm --> OCI
 TComm --> AL

Message Types

class MessageType(Enum):
 TASK_REQUEST = "task_request" # Task request
 NOTIFICATION = "notification" # Notification
 OPINION_REQUEST = "opinion_request" # Opinion request
 OPINION_RESPONSE = "opinion_response" # Opinion response
 STATUS_REPORT = "status_report" # Status report
 ERROR = "error" # Error

Key Function Flows

Input Reception (Discord -> Agent)

User: "@gcp-monitor check server status"
 -> DiscordBot.on_message
 -> UserCommAgent._parse_command (target: gcp-monitor)
 -> TeamCommunicator.send_to_agent
 -> Discord: "Request forwarded to gcp-monitor."

Opinion Request (Agent -> Discord)

gcp-monitor: "Clean up disk?" -> user_comm
 -> DiscordBot.ask_opinion (wait for button or reply)
 -> User response
 -> TeamCommunicator.send_to_agent (forward response)

Notification/Report (Agent -> Discord)

oci-monitor: "Disk 92% warning" -> user_comm
 -> DiscordBot.send_message (Embed format)

3. Lightweight Architecture Without Redis

Why Remove Redis?

Item	With Redis	With In-Memory
Thread Lock	Redis SET NX	Python dict
Event Distribution	Redis Streams	Direct SSE
State Storage	Redis Cache	Memory cache

Conclusion: In-memory is sufficient for single-instance environments

Gateway Structure

flowchart TB
 subgraph GW[Gateway Service]
 Bot[Discord Bot]
 subgraph C[Core Components]
 Lock[Thread Lock]
 Cache[Message Cache]
 SSEMgr[SSE Manager]
 end
 end
 DAPI[Discord API] <--> Bot
 Bot --> Lock
 Bot --> Cache
 Bot --> SSEMgr
 SSEMgr --> Clients[WebSocket Clients]

Component Details

Module	Role	Features
Discord Bot	WebSocket connection	Auto-reconnect
Thread Lock	Concurrency control	5min timeout
Message Cache	Message storage	Max 1000 items
SSE Manager	Real-time delivery	Broadcast to all MCPs

4. MCP Selection: 4-Stage Hybrid

Selection Priority

Rank	Method	Example	Description
1	Slash Command	`/gcp status`	Most explicit
2	@Mention	`@gcp-monitor status`	Natural conversation
3	Keyword Detection	`gcp server status`	Auto keyword recognition
4	Channel Assignment	#gcp-monitoring	Channel default MCP

Fallback Order

flowchart TD
 A[Message Received] --> B{Slash Command?}
 B -->|Yes| C[Route to MCP]
 B -->|No| D{Mention?}
 D -->|Yes| C
 D -->|No| E{Keyword?}
 E -->|Yes| C
 E -->|No| F{Channel Default?}
 F -->|Yes| C
 F -->|No| G[Broadcast]

Slash Command List

Command	MCP	Description
`/gcp status [server]`	gcp-mcp	GCP server status
`/gcp list`	gcp-mcp	GCP instance list
`/oci status [server]`	oci-mcp	OCI server status
`/oci list`	oci-mcp	OCI instance list
`/db query <sql>`	db-mcp	Execute DB query
`/db list`	db-mcp	DB list
`/alert check`	alert-mcp	Check alerts

5. Thread Lock Rules

Lock Behavior

sequenceDiagram
 participant M1 as gcp-mcp
 participant GW as Gateway
 participant M2 as oci-mcp
 participant DT as Discord Thread

 Note over M1,DT: Lock Acquisition
 M1->>+GW: Lock request
 GW-->>-M1: Lock acquired
 M1->>DT: Send response

 Note over M2,GW: Lock Conflict
 M2->>GW: Lock request
 GW-->>M2: Lock failed

 Note over M1,GW: 5min timeout
 GW->>GW: Auto-release lock

 Note over M2,GW: Lock Retry
 M2->>+GW: Lock request
 GW-->>-M2: Lock acquired

Lock API

Method	Endpoint	Description
`POST`	`/api/threads/{id}/acquire`	Acquire lock
`POST`	`/api/threads/{id}/release`	Release lock
`GET`	`/api/threads/{id}/lock`	Check lock status

Request/Response Example

Lock Acquire Request

POST /api/threads/123456/acquire
{
 "agent_name": "gcp-mcp",
 "timeout": 300
}

Lock Acquire Response

{
 "acquired": true,
 "thread_id": "123456",
 "agent": "gcp-mcp"
}

6. MCP Tools (8)

Tool List

Tool	Description	Key Parameters
`discord_send_message`	Send message	channel_id, content
`discord_get_messages`	Get messages	channel_id, limit
`discord_wait_for_message`	Wait for message	channel_id, timeout
`discord_create_thread`	Create thread	channel_id, message_id
`discord_list_threads`	List threads	channel_id
`discord_archive_thread`	Archive thread	thread_id
`discord_acquire_thread`	Acquire lock	thread_id, agent_name
`discord_release_thread`	Release lock	thread_id, agent_name

Tool Relationships

flowchart LR
 subgraph Lock[Lock Tools]
 Acquire[acquire_thread]
 Release[release_thread]
 end
 subgraph Thread[Thread Tools]
 Create[create_thread]
 List[list_threads]
 Archive[archive_thread]
 end
 subgraph Msg[Message Tools]
 Send[send_message]
 Get[get_messages]
 Wait[wait_for_message]
 end

 Acquire --> Create
 Create --> Send
 Send --> Release

Usage Examples

# Send message
discord_send_message(
 channel_id="123456789",
 content="Server status: OK"
)

# Create thread
discord_create_thread(
 channel_id="123456789",
 message_id="987654321",
 name="Status Check"
)

# Acquire lock
discord_acquire_thread(
 thread_id="111222333",
 agent_name="gcp-mcp",
 timeout=300
)

7. File Structure

flowchart TB
 subgraph P[server_monitor/]
 subgraph Gw[gateway/]
 M1[main.py]
 M2[discord_ws.py]
 M3[thread_lock.py]
 M4[sse.py]
 end
 subgraph Uc[user_comm/]
 A1[agent.py]
 A2[discord_bot.py]
 A3[team_comm.py]
 end
 subgraph Mcp[discord_mcp/]
 S1[server.py]
 end
 subgraph Sh[mcp_shared/]
 MO[monitor/]
 end
 subgraph Doc[docs/]
 D1[MCP_SELECTION_STRATEGY.md]
 D2[MCP_ROUTING_POLICY.md]
 end
 end

Directory Description

Path	Description
`gateway/`	Gateway Service (FastAPI)
`user_comm/`	User Communication Agent
`discord_mcp/`	MCP Server (8 tools)
`mcp_shared/`	Shared MCP tools
`docs/`	Documentation

8. How to Run

Local Execution

# Start Gateway Service
uvicorn gateway.main:app --host 0.0.0.0 --port 8081

# Start user_comm Agent (standalone mode)
python main.py --standalone

# Start user_comm Agent (team mode)
python main.py --team server-monitor

# Health check
curl http://localhost:8081/health

# Response
{"status": "healthy", "discord_connected": true}

Claude Code MCP Configuration

// ~/.claude/settings.json
{
 "mcpServers": {
 "discord-gateway": {
 "command": "python3",
 "args": ["/path/to/discord_mcp/server.py"],
 "env": {
 "GATEWAY_URL": "http://localhost:8081"
 }
 }
 }
}

9. Roadmap

Phase 1: Complete

FastAPI Gateway Service
Discord WebSocket connection
Thread Lock (In-Memory)
SSE broadcast
MCP Server (8 tools)

Phase 2: In Progress

user_comm Agent implementation
Slash command implementation
Channel default MCP settings
Keyword auto-detection
Routing configuration file

Phase 3: Optional

API authentication (API Key)
Rate Limiting
Message persistence (SQLite)

Conclusion

We chose a strategy of starting with a lightweight architecture and expanding when needed.

Item	Current	Future
State Storage	In-Memory	SQLite (if needed)
Distributed Lock	Not used	Redis (multi-instance)
Authentication	None	API Key (if needed)
User Communication	Gateway direct	user_comm Agent

The current structure is sufficient for single instances, and we plan to expand incrementally as traffic grows. The user_comm Agent systematizes user communication and improves collaboration with other agents on the team.

Korean Version: 한국어 버전

[Claude Code] Team Agent Communication Architecture

Sat, 28 Feb 2026 14:07:38 +0900

Claude Code Team Agent Communication Architecture Design

Overview

When multiple AI agents collaborate in Claude Code, an efficient communication method is needed. This article shares the communication architecture designed while building a Discord-integrated server monitoring team.

Problem Definition

Claude Code has two types of agents:

Python Processes (Daemon)
- Discord Gateway, user_comm_daemon, etc.
- Always running, filesystem access available
LLM Agents (Created as Tasks)
- gcp-monitor, oci-monitor, alert-manager, etc.
- Use SendMessage tool, Claude Code native communication

Communication between these two types was needed.

Considered Approaches

1. File-based Message Queue (Existing)

Pros: Simple implementation, no dependencies
Cons: Latency (~1s), file management required

2. WebSocket

Pros: Real-time bidirectional communication
Cons: Server/client implementation required

3. gRPC

Pros: Strong type checking, streaming
Cons: proto file management, high complexity

4. SQLite Message Hub (Adopted)

Pros: Fast (~10ms), transactions, no additional dependencies
Cons: Works only on a single machine

Final Architecture

┌─────────────────────────────────────────────────────────────────┐
│ SQLite Message Hub (messages.db) │
│ ~/.claude/teams/{team}/messages.db │
└───────────────────────────┬─────────────────────────────────────┘
 │
 ┌───────────────────┼───────────────────┐
 ↓ ↓ ↓
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Discord │ │ Python │ │ LLM │
│ Gateway │ │ Daemon │ │ Agent │
│ (Direct Access)│ │ (Direct Access)│ │ (MCP Tool) │
└──────────────┘ └──────────────┘ └──────────────┘

SQLite Message Hub Structure

Messages Table

CREATE TABLE messages (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 message_id TEXT UNIQUE NOT NULL,
 sender TEXT NOT NULL,
 recipient TEXT, -- NULL = broadcast
 message_type TEXT DEFAULT 'message',
 content TEXT NOT NULL,
 priority TEXT DEFAULT 'normal',
 metadata TEXT DEFAULT '{}',
 status TEXT DEFAULT 'pending',
 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
 processed_at TIMESTAMP,
 expires_at TIMESTAMP
);

Agent Status Table

CREATE TABLE agent_status (
 agent_name TEXT PRIMARY KEY,
 status TEXT DEFAULT 'offline',
 last_heartbeat TIMESTAMP,
 metadata TEXT DEFAULT '{}'
);

Communication Methods

LLM Agent ↔ LLM Agent

Use SendMessage (Claude Code native)
Auto-managed, idle notification provided

Python ↔ LLM Agent

SQLite Hub + MCP Tool
Python accesses SQLite directly
LLM Agent accesses via MCP Tool

MCP Server Implementation

MCP tools for LLM Agents:

@server.list_tools()
async def list_tools():
 return [
 Tool(name="team_send_message", ...),
 Tool(name="team_read_messages", ...),
 Tool(name="team_broadcast", ...),
 Tool(name="team_get_status", ...),
 Tool(name="team_update_status", ...),
 ]

Message Flow Example

1. Discord user: "Hello"
 ↓
2. Discord Gateway → SQLite: INSERT message
 ↓
3. user_comm Daemon → SQLite: SELECT pending
 ↓
4. user_comm → SQLite: INSERT response
 ↓
5. Discord Gateway → SQLite: SELECT response
 ↓
6. Discord channel: "Hi there! 👋"

Performance Comparison

Method	Latency	Stability	Complexity
File-based	~1000ms	Medium	Low
WebSocket	~5ms	High	Medium
SQLite	~10ms	High	Low

Conclusion

The SQLite Message Hub + MCP Server combination was most suitable for Claude Code team agent communication:

Low Latency: 100x faster than file-based
Stability: Data integrity guaranteed through transactions
Simplicity: Uses Python’s built-in sqlite3 without additional dependencies
Flexibility: Both Python and LLM Agents use the same data source

Code

Core components:

message_hub.py: SQLite Message Hub
team_comm_mcp_server.py: MCP Server
discord_gateway.py: Discord integration gateway
user_comm_daemon.py: Message processing daemon

Korean Version: 한국어 버전

Claude-Code on Yarang's Tech Lair

Building a Blog AI Auto-Comment System (1/3) — Architecture and Implementation

Overview

System Architecture

Overall Data Flow

Components

giscus Configuration

GitHub Webhook Configuration

Flask Worker Implementation

Project Structure

Core Dependencies

Webhook Endpoint

Preventing Infinite Loops

Calling Claude Code CLI

GitHub GraphQL API Integration

Input Sanitization

Audit Logging

Conclusion

Claude Code Discord MCP Plugin - Fixing asdf bun Path Issue

Problem

Root Cause

Solution

Finding the Absolute Path of asdf-installed bun

Applying the Configuration

Summary

References

Claude Code Plugin Development Complete Guide — From plugin.json to Deployment

Step 1: Create Directory Structure

Step 2: Write plugin.json — Core of Metadata

Step 3: Write SKILL.md — Inject Claude’s Expertise

Step 4: agents/ — Define Expert Sub-Agents

Step 5: commands/ — Register Slash Commands

Step 6: hooks/hooks.json — Set Automatic Triggers

Step 7: Register Plugin in marketplace.json

Local Test → Deployment Workflow

Common Mistakes Checklist

Conclusion

References

[Discord Decision MCP] Architecture Design Document

Discord Decision MCP — Architecture Design Document

1. Project Overview

1.1 Purpose

1.2 Key Features

1.3 Version Information

2. Directory Structure

3. Key Module Descriptions

3.1 Server Entry Point (server.py)

3.2 Configuration Management (config.py)

3.3 Discord API Client (bot/)

3.3.1 REST API Client (client.py)

3.3.2 WebSocket Gateway (gateway.py)

3.4 Decision Request Management (decision/)

3.4.1 DecisionManager (manager.py)

3.4.2 DecisionPoller (poller.py)

3.4.3 Response Parser (parser.py)

3.4.4 State Store (state.py)

3.5 MCP Tools (tools/)

3.6 Watcher Daemon (daemon/)

3.6.1 DiscordWatcher (watcher.py)

3.6.2 InboxStore (inbox.py)

4. Data Flow Diagrams

4.1 Decision Request Flow

4.2 Watcher Daemon Flow

4.3 Session Restoration Flow

5. MCP Tools List

5.1 discord_ask_decision

5.2 discord_notify

5.3 discord_report_progress

5.4 discord_check_pending

5.5 discord_read_inbox

5.6 discord_clear_inbox

6. Dependency Information

6.1 Core Dependencies

6.2 Development Dependencies

6.3 CLI Commands

7. State File Format

7.1 Decision State File

7.2 Inbox File

8. Architecture Principles

8.1 Design Principles

3.1 Server Entry Point (`server.py`)

3.2 Configuration Management (`config.py`)

3.3 Discord API Client (`bot/`)

3.3.1 REST API Client (`client.py`)

3.3.2 WebSocket Gateway (`gateway.py`)

3.4 Decision Request Management (`decision/`)

3.4.1 DecisionManager (`manager.py`)

3.4.2 DecisionPoller (`poller.py`)

3.4.3 Response Parser (`parser.py`)

3.4.4 State Store (`state.py`)

3.5 MCP Tools (`tools/`)

3.6 Watcher Daemon (`daemon/`)

3.6.1 DiscordWatcher (`watcher.py`)

3.6.2 InboxStore (`inbox.py`)