OpenCode 사용자를 위해

AGENTS.md는 OpenCode에게 규칙을 알려줍니다.
Maguyva는 코드를 보여줍니다.

OpenCode는 일하는 방식을 AGENTS.md에서 읽고, 나머지는 모두 MCP 서버를 호출합니다. Maguyva는 원격 MCP 서버로서 OpenCode에게 파일 경로와 줄 번호가 담긴, 질의 가능한 저장소 지도를 줍니다.

무료로 시작하기 OpenCode 설정 방법 보기

Free 등급: 저장소 3개, 인덱싱된 저장소 라인 최대 5만 줄, 카드 등록 불필요.

mcp 아래 원격 항목 하나. 로컬에서는 아무것도 돌지 않습니다.

OpenCode에 대해 알아둘 것

OpenCode에만 해당하는 네 가지 사실.

// 설정 파일

opencode.json

프로젝트의 opencode.json에서 mcp 아래에 서버를 추가하세요. 모든 프로젝트에서 쓰려면 ~/.config/opencode/opencode.json에 추가합니다.

// 전송 방식

type: remote

OpenCode는 HTTP로 Maguyva의 엔드포인트에 연결합니다. 로컬에서는 아무것도 실행되지 않고 Node.js도 필요 없습니다.

// 키

환경 변수 참조

OpenCode는 설정 안의 환경 변수를 치환하므로, 헤더는 Bearer {env:MAGUYVA_API_KEY}가 되고 키는 커밋하는 파일에 들어가지 않습니다.

// 컨텍스트 예산

에이전트별로 범위 지정

MCP 서버마다 도구 정의가 컨텍스트에 더해집니다. OpenCode에서는 "maguyva*": false 같은 glob으로 서버의 도구를 전역에서 끄고, 필요한 에이전트에서만 다시 켤 수 있습니다.

AGENTS.md는 작업 합의입니다. 활용하세요.

> /init
# 저장소를 스캔해 AGENTS.md를 작성

OpenCode는 프로젝트 루트의 AGENTS.md와, 개인 규칙용 ~/.config/opencode/AGENTS.md를 읽습니다. AGENTS.md가 없으면 CLAUDE.md로 대체합니다. 이런 용도로 쓰세요:

빌드, 테스트, lint 명령.
에이전트가 지켜야 할 규칙과 경계.
중요한 문서로 가는 포인터.

/init 시점의 스캔은 요약이지 인덱스가 아닙니다. 어제 추가된 함수를 누가 호출하는지 OpenCode에게 알려주지 않습니다.

AGENTS.md가 한계에 부딪히는 곳

OpenCode가 grep과 인내심으로 메우는 세 가지 빈틈.

// 요약은 인덱스가 아니다

AGENTS.md는 중요한 패키지 이름을 댈 수 있습니다. 모든 심볼과 호출 지점을 나열할 수는 없고, 그러려고 해서도 안 됩니다.

// grep은 호출자가 아니라 문자열을 찾는다

텍스트 일치로는 진짜 호출과 주석, 목, 다른 클래스의 같은 이름 메서드를 구분할 수 없습니다.

// 파일은 어긋나기 마련

AGENTS.md는 작성된 날에는 맞습니다. 코드는 계속 움직이고, 파일은 누군가 기억해 낼 때에만 갱신됩니다.

OpenCode의 원격 MCP 서버로서의 Maguyva

mcp 아래 항목 하나로 OpenCode가 얻는 것:

인덱싱된 저장소에 대한 11개의 도구 시맨틱, 구조적(AST), 그래프, 텍스트 검색에 더해 심볼 조회, 의존 요소, 파일 검색까지.
파일 경로와 줄 번호가 포함된 답 285개 이상의 언어에서.
어떤 모델에든 같은 답 OpenCode는 여러 모델 공급자와 함께 동작합니다. 어느 모델이 묻든 Maguyva는 같은 지도를 돌려줍니다.

AGENTS.md는 OpenCode에게 일하는 방법을 알려줍니다.
Maguyva는 OpenCode에게 일의 근거를 줍니다.

두 가지 워크플로

같은 터미널에서 지도에 물어보세요.

// workflow 01

여러 패키지에 걸쳐 공유 타입 이름 바꾸기

opencode> OrderStatus를 FulfillmentStatus로 이름 바꿔 줘

dependency_search("OrderStatus", dependents)
  패키지 8개에 걸친 참조 23건
structural_search(switch_statement, "OrderStatus")
  망라형 switch 4개

→ OpenCode가 switch까지 포함해 전체 목록을 편집합니다.
[exit 0]

망라형 switch야말로 텍스트 검색이 놓치고 컴파일러가 뒤늦게 잡아내는 곳입니다.

// workflow 02

코드와 문서 구분하기

opencode> FEATURE_BULK_EXPORT는 어디서 읽나요?

text_pattern_search("FEATURE_BULK_EXPORT")
  src/config/flags.ts:17
  src/export/bulk.ts:5
  docs/flags.md:40   ← 문서뿐

→ 코드 경로 두 개, 낡은 문서 하나.
[exit 0]

정확히 일치하는 결과가 경로와 함께 오므로, OpenCode는 어느 쪽을 편집하기 전에 코드와 문서를 구분할 수 있습니다.

OpenCode에서 설정하기

세 단계로 끝. Free 등급: 저장소 3개, 인덱싱된 저장소 라인 최대 5만 줄, 카드 등록 불필요.

// step 01

maguyva.ai에서 저장소 인덱싱하기

답을 채점할 수 있도록 이미 잘 아는 저장소를 고르세요.

// step 02

opencode.json의 mcp 아래에 Maguyva 추가하기

opencode.json

{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}

// step 03

키를 export하고 연결 확인하기

OpenCode를 실행하는 셸에서 MAGUYVA_API_KEY를 설정하세요. opencode mcp list가 설정된 서버를 모두 보여줍니다. 그런 다음 이미 답을 아는 질문 하나를 해보세요.