@apps-in-toss/ax 0.7.1

package/README.md

@@ -0,0 +1,149 @@
+# AX (AppsInToss eXperience)
+
+AI 어시스턴트가 AppsInToss 미니앱 개발을 도울 수 있도록 설계된 MCP(Model Context Protocol) 서버입니다.
+
+## 주요 기능
+
+AX는 AI 어시스턴트에게 AppsInToss Developer Center의 문서를 제공하여, 토스 미니앱 개발에 대한 정확하고 컨텍스트 기반의 지원을 가능하게 합니다.
+
+### MCP Tools
+
+| 도구 | 설명 |
+|------|------|
+| `search_docs` | AppsInToss 문서 검색 |
+| `get_doc` | 검색 결과의 문서 전체 내용 조회 |
+| `search_tds_rn_docs` | TDS React Native 문서 검색 |
+| `get_tds_rn_doc` | TDS React Native 문서 전체 내용 조회 |
+| `search_tds_web_docs` | TDS Web 문서 검색 |
+| `get_tds_web_doc` | TDS Web 문서 전체 내용 조회 |
+
+### 지원 문서
+
+- **AppsInToss Developer Center** - 미니앱 개발 가이드
+- **TDS React Native** - 토스 디자인 시스템 (React Native)
+- **TDS Web** - 토스 디자인 시스템 (WebView)
+
+## 설치
+
+### Homebrew (macOS/Linux)
+
+```bash
+brew tap toss/tap
+brew install ax
+```
+
+### Scoop (Windows)
+
+```powershell
+scoop bucket add toss https://github.com/toss/scoop-bucket
+scoop install ax
+```
+
+### npm
+
+```bash
+npm install -g @apps-in-toss/ax
+```
+
+## 사용법
+
+### MCP 서버 시작
+
+```bash
+ax mcp
+ax mcp --disable-usage-stats
+```
+
+AX는 제품 개선과 안정적인 운영을 위해 명령 실행, MCP 도구 호출, 성공 여부, 실행 시간 같은 사용 통계를 수집합니다.
+사용 통계 수집을 원하지 않으면 `--disable-usage-stats` 옵션을 추가하세요.
+
+### Cursor/Claude에서 사용
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=apps-in-toss&config=eyJjb21tYW5kIjoiYXgiLCJhcmdzIjpbIm1jcCJdfQ==)
+
+또는 `.cursor/mcp.json` / `claude_desktop_config.json`에 다음을 추가하세요:
+
+```json
+{
+  "mcpServers": {
+    "apps-in-toss": {
+      "command": "ax",
+      "args": [
+        "mcp"
+      ]
+    }
+  }
+}
+```
+
+## 프로젝트 구조
+
+```
+apps-in-toss-ax/
+├── cmd/                    # CLI 명령어 정의
+├── internal/               # 내부 패키지
+│   ├── httputil/          # HTTP 유틸리티
+│   └── utils/             # 공통 유틸리티
+├── pkg/                    # 핵심 패키지
+│   ├── app/               # 애플리케이션 진입점
+│   ├── docs/              # 문서 관리
+│   ├── docid/             # 문서 ID 생성
+│   ├── features/          # 기능 구성
+│   ├── fetcher/           # HTTP 클라이언트
+│   ├── instrumentation/   # 사용 통계 수집
+│   ├── llms/              # llms.txt 파서
+│   ├── mcp/               # MCP 서버 구현
+│   └── search/            # 문서 검색 엔진
+├── tools/                  # 배포 도구
+│   ├── publish/           # 패키지 매니저 배포
+│   └── shared/            # 공유 유틸리티
+├── scripts/                # 스크립트
+├── main.go                # 메인 진입점
+├── go.mod                 # Go 모듈 정의
+├── Makefile               # 빌드 명령어
+└── package.json           # npm 패키지 정의
+```
+
+## 개발
+
+### 빌드
+
+```bash
+make build
+# 또는
+go build -o ax
+```
+
+### 테스트
+
+```bash
+go test ./...
+```
+
+### 로컬 실행
+
+```bash
+./ax mcp
+```
+
+## AppsInToss란?
+
+**AppsInToss**는 토스 앱 내에서 미니앱을 제공할 수 있는 플랫폼입니다. 3,000만 토스 사용자에게 서비스를 노출하고, SDK와 API를 활용해 빠르게 개발할 수 있습니다.
+
+### 주요 개념
+
+| 용어 | 설명 |
+|------|------|
+| **Granite** | 미니앱 개발 프레임워크 (구 Bedrock, v1.0+) |
+| **TDS** | Toss Design System - 비게임 미니앱 필수 |
+
+### 개발 방식
+
+- **React Native**: 네이티브에 가까운 성능
+- **WebView**: 웹 기술 활용
+
+## 관련 링크
+
+- [AppsInToss Developer Center](https://developers-apps-in-toss.toss.im)
+- [TDS React Native](https://tossmini-docs.toss.im/tds-react-native)
+- [TDS Web](https://tossmini-docs.toss.im/tds-mobile)

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@apps-in-toss/ax",
+  "version": "0.7.1",
+  "description": "MCP server that provides AppsInToss documentation to AI assistants",
+  "type": "module",
+  "engines": {
+    "node": ">=22.9.0",
+    "npm": ">=8"
+  },
+  "repository": "toss/apps-in-toss-ax",
+  "homepage": "https://github.com/toss/apps-in-toss-ax#readme",
+  "bugs": "https://github.com/toss/apps-in-toss-ax/issues",
+  "scripts": {
+    "prepack": "node -e \"require('fs').rmSync('bin', { recursive: true, force: true })\"",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "dependencies": {
+    "bin-links": "^6.0.0",
+    "https-proxy-agent": "^7.0.2",
+    "node-fetch": "^3.3.2",
+    "tar": "7.5.16"
+  },
+  "bin": {
+    "ax": "bin/ax"
+  },
+  "files": [
+    "scripts/postinstall.js"
+  ],
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "keywords": [
+    "apps-in-toss",
+    "toss",
+    "mcp",
+    "mcp-server",
+    "mini-app",
+    "cli"
+  ],
+  "author": "Viva Republica, Inc.",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+
+// Ref 1: https://github.com/sanathkr/go-npm
+// Ref 2: https://medium.com/xendit-engineering/how-we-repurposed-npm-to-publish-and-distribute-our-go-binaries-for-internal-cli-23981b80911b
+"use strict";
+
+import binLinks from "bin-links";
+import { createHash } from "crypto";
+import fs from "fs";
+import fetch from "node-fetch";
+import { Agent } from "https";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import path from "path";
+import { extract } from "tar";
+import zlib from "zlib";
+
+// Mapping from Node's `process.arch` to Golang's `$GOARCH`
+const ARCH_MAPPING = {
+  x64: "amd64",
+  arm64: "arm64",
+};
+
+// Mapping between Node's `process.platform` to Golang's
+const PLATFORM_MAPPING = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+};
+
+const arch = ARCH_MAPPING[process.arch];
+const platform = PLATFORM_MAPPING[process.platform];
+
+// TODO: import pkg from "../package.json" assert { type: "json" };
+const readPackageJson = async () => {
+  const contents = await fs.promises.readFile("package.json");
+  return JSON.parse(contents);
+};
+
+// Release artifacts are named after the binary (GoReleaser project name),
+// not the scoped npm package name.
+const getBinaryName = (packageJson) => Object.keys(packageJson.bin)[0];
+
+// Build the download url from package.json
+const getDownloadUrl = (packageJson) => {
+  const binName = getBinaryName(packageJson);
+  const version = packageJson.version;
+  const repo = packageJson.repository;
+  const url = `https://github.com/${repo}/releases/download/v${version}/${binName}_${platform}_${arch}.tar.gz`;
+  return url;
+};
+
+const fetchAndParseCheckSumFile = async (packageJson, agent) => {
+  const version = packageJson.version;
+  const binName = getBinaryName(packageJson);
+  const repo = packageJson.repository;
+  const checksumFileUrl = `https://github.com/${repo}/releases/download/v${version}/${binName}_${version}_checksums.txt`;
+
+  // Fetch the checksum file
+  console.info("Downloading", checksumFileUrl);
+  const response = await fetch(checksumFileUrl, { agent });
+  if (response.ok) {
+    const checkSumContent = await response.text();
+    const lines = checkSumContent.split("\n");
+
+    const checksums = {};
+    for (const line of lines) {
+      const [checksum, packageName] = line.split(/\s+/);
+      checksums[packageName] = checksum;
+    }
+
+    return checksums;
+  } else {
+    console.error(
+      "Could not fetch checksum file",
+      response.status,
+      response.statusText
+    );
+  }
+};
+
+const errChecksum = "Checksum mismatch. Downloaded data might be corrupted.";
+const errUnsupported = `Installation is not supported for ${process.platform} ${process.arch}`;
+
+/**
+ * Reads the configuration from application's package.json,
+ * downloads the binary from package url and stores at
+ * ./bin in the package's root.
+ *
+ *  See: https://docs.npmjs.com/files/package.json#bin
+ */
+async function main() {
+  if (!arch || !platform) {
+    throw errUnsupported;
+  }
+
+  // Read from package.json and prepare for the installation.
+  const pkg = await readPackageJson();
+  const binCmd = getBinaryName(pkg);
+  if (platform === "windows") {
+    // Update bin path in package.json
+    pkg.bin[binCmd] += ".exe";
+  }
+
+  // Prepare the installation path by creating the directory if it doesn't exist.
+  const binPath = pkg.bin[binCmd];
+  const binDir = path.dirname(binPath);
+  await fs.promises.mkdir(binDir, { recursive: true });
+
+  // Create the agent that will be used for all the fetch requests later.
+  const proxyUrl =
+    process.env.npm_config_https_proxy ||
+    process.env.npm_config_http_proxy ||
+    process.env.npm_config_proxy;
+  // Keeps the TCP connection alive when sending multiple requests
+  // Ref: https://github.com/node-fetch/node-fetch/issues/1735
+  const agent = proxyUrl
+    ? new HttpsProxyAgent(proxyUrl, { keepAlive: true })
+    : new Agent({ keepAlive: true });
+
+  // First, fetch the checksum map.
+  const checksumMap = await fetchAndParseCheckSumFile(pkg, agent);
+
+  // Then, download the binary.
+  const url = getDownloadUrl(pkg);
+  console.info("Downloading", url);
+  const resp = await fetch(url, { agent });
+  if (!resp.ok) {
+    throw `Failed to download ${url}: ${resp.status} ${resp.statusText}`;
+  }
+  const hash = createHash("sha256");
+  const pkgNameWithPlatform = `${binCmd}_${platform}_${arch}.tar.gz`;
+
+  // Then, decompress the binary -- we will first Un-GZip, then we will untar.
+  const ungz = zlib.createGunzip();
+  const binName = path.basename(binPath);
+  const untar = extract({ cwd: binDir }, [binName]);
+
+  // Update the hash with the binary data as it's being downloaded.
+  resp.body
+    .on("data", (chunk) => {
+      hash.update(chunk);
+    })
+    // Pipe the data to the ungz stream.
+    .pipe(ungz);
+
+  // After the ungz stream has ended, verify the checksum.
+  ungz
+    .on("end", () => {
+      const expectedChecksum = checksumMap?.[pkgNameWithPlatform];
+      // Skip verification if we can't find the file checksum
+      if (!expectedChecksum) {
+        console.warn("Skipping checksum verification");
+        return;
+      }
+      const calculatedChecksum = hash.digest("hex");
+      if (calculatedChecksum !== expectedChecksum) {
+        throw errChecksum;
+      }
+      console.info("Checksum verified.");
+    })
+    // Pipe the data to the untar stream.
+    .pipe(untar);
+
+  // Wait for the untar stream to finish.
+  await new Promise((resolve, reject) => {
+    untar.on("error", reject);
+    untar.on("end", () => resolve());
+  });
+
+  // npm links bins before postinstall runs and silently skips the
+  // then-missing binary, so re-link here. global/top make the link land in
+  // the global bin dir on `npm install -g`.
+  const isGlobalInstall = process.env.npm_config_global === "true";
+  await binLinks({
+    path: path.resolve("."),
+    pkg: { ...pkg, bin: { [binCmd]: binPath } },
+    global: isGlobalInstall,
+    top: isGlobalInstall,
+    force: true,
+  });
+
+  console.info("Installed AppsInToss CLI successfully");
+}
+
+await main();