OpenCode CLI에서 Discourse MCP 설정

위키 사용자
, ,
1

이 가이드는 Discourse MCP를 OpenCode CLI에 설치하는 테스트된 절차를 제공합니다. 다른 MCP 클라이언트를 사용하고 있다면, Codex CLI용 가이드도 작성해 두었습니다.

LLM을 활용하세요! LLM은 지시를 따르는 데 매우 뛰어나며 설치를 대신 수행할 수 있습니다. LLM에게 이 가이드의 URL을 지정하고 설치를 요청하세요. 이해가 안 되는 단계가 있다면 설명을 요청할 수도 있습니다.

사전 요구 사항

  • Node.js 설치 (24 LTS 권장)
  • OpenCode CLI 설치
  • 대상 Discourse 포럼에 대한 일반 사용자 접근 권한 (관리자 권한 불필요!)

여기에는 세 가지 서로 다른 구성 요소가 있다는 점을 인식하는 것이 중요합니다:

  1. 원격 Discourse 포럼: 데이터의 출처이자 작업의 대상입니다.

  1. Discourse MCP 서버: Discourse에 연결하고 OpenCode가 Discourse와 상호작용할 수 있도록 API를 제공하는 오픈소스 로컬 실행 도구입니다. NPX 패키지로 설치되며 OpenCode CLI에 의해 필요할 때 시작됩니다.

  1. OpenCode CLI: MCP 서버에 연결하고 MCP API를 통해 Discourse와 상호작용하는 인터페이스를 제공하는 MCP 클라이언트입니다.

1. 사용자 API 키 생성

이 과정은 Discourse에 대한 인증을 수행하며, 여기서 API 키를 얻습니다. npx는 코드를 다운로드하고 실행하므로, 전통적인 의미의 설치는 필요하지 않습니다.

터미널에서 다음을 실행하세요:

npx @discourse/mcp@latest generate-user-api-key \
  --site =DISCOURSE-FORUM= \
  --save-to =PROFILE-PATH=/=NAME=.json

예시:

npx @discourse/mcp@latest generate-user-api-key \
  --site https://meta.discourse.org \
  --save-to ~/.config/opencode/discourse-profiles/meta.json

브라우저 동의 창을 승인하고 로그인 능력을 증명하는 암호화된 데이터를 복사하여 =PROFILE-PATH=에 저장된 API 키를 생성하세요. 이 키는 MCP 서버에서 사용됩니다.

API 키는 사용자로 포럼에 대한 접근 권한과 동일한 수준의 접근 권한을 가집니다.

2. OpenCode CLI에 MCP 서버 추가

~/.config/opencode/opencode.jsonc의 OpenCode 설정 파일을 편집하고 mcp 섹션에 다음 항목을 추가하세요:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    // ... 기타 MCP 서버 ...
    "discourse-=NAME=-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@discourse/mcp@latest",
        "--profile",
        "=PROFILE-PATH=/=NAME=.json",
      ],
      "enabled": true,
      "environment": {},
    },
  },
}

예시:

"discourse-meta-mcp": {
  "type": "local",
  "command": [
    "npx",
    "-y",
    "@discourse/mcp@latest",
    "--profile",
    "/home/marcus/.config/opencode/discourse-profiles/meta.json"
  ],
  "enabled": true,
  "environment": {},
},

MCP 서버는 OpenCode를 시작할 때 OpenCode CLI에 의해 npx로 필요할 때 시작됩니다. =PROFILE-PATH=의 프로필을 사용하도록 구성되며, 기본적으로 읽기 전용입니다.

3. OpenCode CLI 재시작

OpenCode를 완전히 재시작하여 설정을 다시 로드하고 MCP 서버에 연결되도록 하세요.

오류 없이 시작되면 Discourse MCP 서버가 작동하고 있음을 의미합니다. OpenCode에게 Discourse 포럼에서 정보를 참조하도록 요청할 수 있습니다 - 특히 공개되지 않았지만 사용자가 접근할 수 있는 정보를 포함하여 - 이를 통해 사용자로 연결되고 있는지 확인할 수 있습니다.

4. 쓰기 기능 활성화 (선택 사항)

기본적으로 Discourse MCP 서버는 읽기 전용 모드로 실행됩니다. 쓰기 작업(게시물, 주제, 사용자 생성 등)을 활성화하려면 프로필 JSON 파일에 두 개의 플래그를 추가해야 합니다.

=PROFILE-PATH=/=NAME=.json을 편집하고 auth_pairs 배열의 형제 요소로 "read_only": false와 "allow_writes": true를 추가하세요:

{
  "read_only": false,
  "allow_writes": true,
  "auth_pairs": [
    {
      "site": "=DISCOURSE-FORUM=",
      "user_api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "user_api_client_id": "discourse-mcp"
    }
  ]
}

예시:

{
  "read_only": false,
  "allow_writes": true,
  "auth_pairs": [
    {
      "site": "https://meta.discourse.org",
      "user_api_key": "abc123def456ghi789jkl012mno345pqr",
      "user_api_client_id": "discourse-mcp"
    }
  ]
}

이 플래그를 추가한 후 변경 사항이 적용되도록 OpenCode CLI를 재시작하세요. 이제 MCP 서버는 다음과 같은 쓰기 작업을 허용합니다:

  • 주제 생성 및 업데이트
  • 게시물 및 답변 생성
  • 초안 관리
  • 파일 업로드
  • 카테고리 생성 (권한이 있는 경우)
  • 사용자 관리 (관리자 권한이 있는 경우)

경고: 쓰기 작업은 사용자 계정의 권한을 사용합니다. 생성된 콘텐츠는 사용자가 수동으로 생성한 것처럼 표시됩니다. 쓰기 기능을 책임감 있게 사용하세요.

여러 Discourse 인스턴스 관리

다른 프로필 파일과 MCP 서버 이름을 사용하여 프로세스를 반복함으로써 여러 Discourse 포럼을 추가할 수 있습니다:

"discourse-meta-mcp": {
  "type": "local",
  "command": [
    "npx", "-y", "@discourse/mcp@latest",
    "--profile", "/home/username/.config/opencode/discourse-profiles/meta.json"
  ],
  "enabled": true,
  "environment": {},
},
"discourse-mycommunity-mcp": {
  "type": "local",
  "command": [
    "npx", "-y", "@discourse/mcp@latest",
    "--profile", "/home/username/.config/opencode/discourse-profiles/mycommunity.json"
  ],
  "enabled": true,
  "environment": {},
},

설정 파일

주요 파일은 두 개입니다:

  1. =OPENCODE-CONFIG= - ~/.config/opencode/opencode.jsonc에 위치한 OpenCode CLI 설정 파일로, MCP 서버 설정을 포함합니다.

  2. =PROFILE-PATH= - Discourse MCP 서버의 프로필로, Discourse 연결을 위한 API 키 및 기타 설정을 포함합니다.

OpenCode 설정

MCP 서버 연결 설정은 =OPENCODE-CONFIG= (일반적으로 ~/.config/opencode/opencode.jsonc)에 있습니다:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "discourse-=NAME=-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@discourse/mcp@latest",
        "--profile",
        "=PROFILE-PATH=/=NAME=.json",
      ],
      "enabled": true,
      "environment": {},
    },
  },
}

OpenCode MCP 설정 문서: OpenCode 문서

Discourse MCP 설정

Discourse MCP 서버 자체의 설정은 =PROFILE-PATH=/=NAME=.json=에 있습니다:

{
  "auth_pairs": [
    {
      "site": "=DISCOURSE-FORUM=",
      "user_api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "user_api_client_id": "discourse-mcp"
    }
  ]
}

Discourse MCP 설정 문서: GitHub - discourse/discourse-mcp

보안 모범 사례

다음과 하는 것이 권장됩니다:

  1. 프로필 파일을 전용 디렉터리에 저장 (예: ~/.config/opencode/discourse-profiles/)
  2. 버전 관리로 dotfiles를 추적하고 있다면 해당 디렉터리를 .gitignore에 추가
  3. 프로필 파일에 설명적인 이름 사용 (예: meta.json, mycommunity.json)
  4. API 키는 사용자 계정과 동일한 접근 권한을 가지므로 비공개로 유지

문제 해결

  • 연결 문제: opencode.jsonc의 프로필 경로가 정확한지 및 파일이 존재하는지 확인
  • 인증 오류: Discourse 사용자 설정에서 API 키가 폐기되지 않았는지 확인
  • 권한 오류: Discourse 인스턴스에 필요한 권한이 있는지 확인
  • 재시작 필요: opencode.jsonc의 변경 사항은 OpenCode CLI 재시작이 필요합니다
3개의 좋아요