Skip to main content
Glama
deenesjakoru
imshashwatsingh

github-assistant-mcp

by imshashwatsingh
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

GitHub Assistant MCP

Model Context Protocol(MCP) 프로토콜을 사용하는 작고 독립적인 서버로, AI 코딩 어시스턴트(예: OpenCode)에 5개의 읽기 전용 도구를 노출합니다. 이 서버는 어시스턴트가 로컬 워크스페이스를 검사하고 클린하고 샌드박스 처리된 stdio 전송을 통해 공개 GitHub 프로필을 가져올 수 있게 해줍니다.

"OpenCode용 간단한 GitHub MCP 서버."

목차

Related MCP server: chatgpt-codex-local-mcp

개요

이 서버는 OpenCode가 자식 프로세스로 시작하는 로컬 MCP 서버입니다. 이 서버는 stdio(stdin/stdout)를 통해 MCP 프로토콜을 사용하며 5개의 도구를 등록합니다. 어시스턴트가 해당 도구를 호출하면 서버가 작업(파일시스템 읽기, git diff, 또는 GitHub API 호출)을 수행하고 구조화된 텍스트 결과를 반환합니다.

파일시스템에 접근하는 모든 작업은 단일 WORKSPACE_ROOT 디렉터리로 제한되므로, 어시스턴트는 프로젝트 폴더 밖을 읽거나 벗어날 수 없습니다.

작동 방식 (아키텍처)

┌─────────────────────────┐         stdio (MCP/JSON-RPC)        ┌──────────────────────────────┐
│                         │  ───────────────────────────────▶  │   github-assistant  (this)   │
│     OpenCode / AI       │  tool call: get_github_profile     │                              │
│     Assistant           │                                    │  ┌────────────────────────┐  │
│                         │  ◀───────────────────────────────  │  │      McpServer          │  │
│  - sees 5 tools         │     result (JSON text)             │  │  (server.ts)            │  │
│  - calls them           │                                    │  └───────────┬────────────┘  │
│  - sandbox enforced     │                                    │              │ registerTools  │
└─────────────────────────┘                                    └──────────────┼──────────────┘
                                                                          ▼
                                                         ┌────────────────────────────────┐
                                                         │  tools.ts  (5 tool handlers)   │
                                                         └───┬──────┬──────┬──────┬─────┬──┘
                                          ┌───────────────┘      │      │      │     │
                                          ▼                      ▼      ▼      ▼     ▼
                                   ┌────────────┐        ┌────────────┐ ┌─────────┐ ┌────────────┐
                                   │ github.ts  │        │ workspace.ts│ │ git.ts │ │ paths.ts   │
                                   │ GitHub API │        │ list/read/  │ │ git diff│ │ resolve    │
                                   │ (fetch)   │        │ search      │ │         │ │ sandbox    │
                                   └─────┬──────┘        └─────┬──────┘ └────┬────┘ └─────┬──────┘
                                         │                    │            │           │
                                         ▼                    ▼            ▼           ▼
                                 api.github.com       WORKSPACE_ROOT/*   git CLI    config.ts
                                                        (files only)   (cwd=root)  WORKSPACE_ROOT

단일 도구 호출의 데이터 흐름:

Assistant ──JSON-RPC request──▶ McpServer
                                     │
                                     ▼
                               tool handler (tools.ts)
                                     │  validates args with zod
                                     ▼
                          business logic (github / workspace / git / paths)
                                     │  resolveWorkspacePath() enforces sandbox
                                     ▼
                          result helper (result.ts) → { content: [{ type:"text", text }] }
                                     │
                                     ▼
Assistant ◀──JSON-RPC response── McpServer

전송 및 수명 주기

  • 유형: local — OpenCode가 서버를 자식 프로세스로 실행합니다.

  • 전송: @modelcontextprotocol/server/stdio의 serveStdio()를 통한 stdio.

  • 시작 순서:

    1. node dist/server.js가 실행됩니다(opencode.json에 선언, cwd = ".").

    2. createServer()가 github-assistant(v1.0.0)라는 이름의 McpServer를 만듭니다.

    3. registerTools(server)가 5개의 도구를 등록합니다.

    4. serveStdio(createServer)가 stdin에서 JSON-RPC 메시지를 읽고 stdout으로 결과를 쓰기 시작합니다.

  • 종료: 세션이 끝나면 OpenCode가 프로세스를 종료합니다.

프로세스가 OpenCode의 작업 디렉터리를 상속하므로 WORKSPACE_ROOT는 프로젝트 디렉터리(path.resolve(process.cwd()))로 결정됩니다.

도구 참조

모든 도구는 src/tools.ts에 등록되며 MCP 텍스트 결과(JSON 또는 일반 텍스트)를 반환합니다.

1. get_github_profile

공개 GitHub 프로필(imshashwatsingh)을 가져옵니다.

  • 입력: 없음

  • 백엔드: Accept: application/vnd.github+json 및 User-Agent 헤더를 사용하여 https://api.github.com/users/imshashwatsingh에 fetch() 호출.

  • 반환값: 사용자 이름, 이름, 회사, 위치, 팔로워, 팔로잉, 공개 저장소/게시글 수, 생성/업데이트 타임스탬프.

  • 파일: src/github.ts

2. list_files

워크스페이스 디렉터리의 파일을 깊이 제한과 함께 나열합니다.

  • 입력: path (기본값 "."), maxDepth (0–10, 기본값 3)

  • 백엔드: src/workspace.ts의 재귀 collectFiles() — 심볼릭 링크를 건너뛰고(순환 방지) 구성된 디렉터리를 무시하며(node_modules, .git, dist, .next, coverage, .cache), MAX_RESULTS(500)로 제한합니다.

  • 반환: 작업공간 루트, 파일 수, 상대 파일 경로.

  • 파일: src/workspace.ts

3. read_file

선택적 줄 범위로 UTF-8 텍스트 파일을 읽습니다.

  • 입력: path(필수), startLine(선택), endLine(선택)

  • 백엔드: readWorkspaceFile() — 샌드박스를 적용하고 파일이 아닌 것을 거부하며 MAX_FILE_SIZE(1 MB)보다 큰 파일을 거부하고 바이너리 확장자를 거부합니다. 줄 번호가 매겨진 내용을 반환합니다.

  • 반환: line: text 접두사가 있는 파일 내용.

  • 파일: src/workspace.ts

4. search_context

작업 공간 전체에서 컨텍스트와 함께 키워드 검색.

  • 입력: query (필수), path (기본값 "."), maxResults (1–10), contextLines (0–10, 기본 2)

  • 백엔드: searchContext()가 텍스트 파일과 크기 제한이 있는 파일만 필터링한 후 각 줄을 스캔하고(대소문자 구분 없음) contextLines 주변 컨텍스트를 캡처합니다.

  • 반환: 쿼리, 검색 경로, 파일/줄/컨텍스트가 포함된 일치 항목.

  • 파일: src/workspace.ts

5. summarize_diff

현재 Git diff를 검사하고 구조화된 결과를 반환합니다.

  • 입력: staged(기본값 false), path(선택 사항), maxDiffChars(1000–50000)

  • 백엔드: git diff --no-ext-diff --unified=3 명령을 실행합니다(--cached/base ref 포함). 통계는 diff 텍스트에서 직접 파싱됩니다. diff는 maxDiffChars로 잘립니다.

  • 반환: 변경된 파일 수, 파일별 통계, 원시 diff — 변경 사항이 없으면 빈 결과.

  • 파일: src/git.ts

보안 모델

서버는 읽기 전용 및 샌드박스입니다:

우려 사항

보호 장치

경로 이탈(../../etc/passwd)

resolveWorkspacePath()가 경로를 확인하고 WORKSPACE_ROOT를 벗어나면 예외를 발생시킵니다.

바이너리 파일 읽기

isProbablyTextFile()이 비텍스트 확장자(png, exe, pdf 등)를 차단합니다.

대용량 파일

read_file/search_context가 MAX_FILE_SIZE(1MB)를 초과하는 파일을 거부합니다.

심볼릭 링크

collectFiles()가 심볼릭 링크를 완전히 건너뜁니다.

디렉터리 폭주

목록/검색이 MAX_RESULTS(500) 및 maxDepth(기본 3)로 제한됩니다.

쓰기/삭제/실행

쓰기, 삭제 또는 임의 셸 실행 API가 없습니다. git만 자식 프로세스로 허용됩니다.

프로젝트 둘러보기

  1. src/server.ts — createServer()가 McpServer를 구성하고 도구를 등록합니다. serve()는 @modelcontextprotocol/sdk의 표준 stdio 서버 전송을 사용합니다.

  2. src/tools.ts — 5개의 도구 정의는 스키마와 핸들러를 매핑합니다. 모든 도구는 MCP 결과를 반환하기 전에 textResult() 또는 errorResult()를 호출합니다.

  3. src/workspace.ts — 파일 시스템 도구(list_files, read_file, search_context)를 구현합니다. 모든 파일 접근은 resolveWorkspacePath()를 통과합니다.

  4. src/git.ts — git_diff 도구를 구현합니다. git diff --no-ext-diff --unified=3을 실행하고 출력에서 통계를 파싱합니다.

  5. src/github.ts — GitHub API 호출을 캡슐화합니다. fetchGitHubProfile(백엔드), getGitHubProfile(도구 래퍼).

  6. src/paths.ts — 경로 안전 계층: resolveWorkspacePath()(샌드박스 게이트)와 isProbablyTextFile().

  7. src/config.ts — WORKSPACE_ROOT, MAX_RESULTS, MAX_FILE_SIZE, GITHUB_USERNAME, IGNORED_DIRECTORIES, BINARY_EXTENSIONS와 같은 모든 상수.

  8. src/result.ts — 도구가 반환하는 결과를 만들기 위한 작은 헬퍼.

구성

opencode.json(프로젝트 루트)이 서버를 선언합니다:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github-assistant": {
      "type": "local",
      "command": ["node", "dist/server.js"],
      "cwd": ".",
      "enabled": true
    }
  }
}

서버 내부 동작은 src/config.ts의 상수로 조정됩니다:

상수

기본값

의미

WORKSPACE_ROOT

path.resolve(process.cwd())

샌드박스 루트(프로젝트 디렉터리)

MAX_FILE_SIZE

1 MB

읽을 수 있는 최대 파일 크기

MAX_RESULTS

500

목록/검색의 최대 파일 수

GITHUB_USERNAME

imshashwatsingh

프로필 대상

IGNORED_DIRECTORIES

node_modules, .git, dist 등

순회 시 건너뜀

BINARY_EXTENSIONS

png, exe, pdf 등

비텍스트로 처리

빌드 및 실행

# install dependencies
npm install

# compile TypeScript -> dist/
npm run build

# start the server (used by opencode.json)
npm start

# run directly from source (no build step)
npm run dev

# the workspace must be a git repo for summarize_diff to work
git init

OpenCode는 빌드된 dist/server.js를 opencode.json에서 자동으로 감지합니다.

파일 구조

github_assistant_mcp/
├── opencode.json          # MCP server declaration for OpenCode
├── package.json           # scripts + dependencies
├── tsconfig.json          # TypeScript config
├── src/
│   ├── server.ts          # Entry point: create + serve McpServer
│   ├── tools.ts           # Registers the 5 tools + handlers
│   ├── config.ts          # Constants, limits, GitHub target
│   ├── paths.ts           # Sandbox path resolution + helpers
│   ├── workspace.ts       # list / read / search filesystem
│   ├── github.ts          # GitHub profile fetch
│   ├── git.ts             # git diff summary + stat parsing
│   └── result.ts          # MCP result/error helpers
└── dist/                  # Compiled output (npm run build)

제한 사항

  • get_github_profile은 단일 하드코딩된 사용자만 대상으로 하며 매개변수화되지 않습니다.

  • summarize_diff는 작업 트리 변경 사항만 보고합니다 — 추적되지 않은 파일은 제외됩니다.

  • 파일 시스템 도구는 워크스페이스로 제한되며 교차 프로젝트 접근이 없습니다.

  • 모든 도구는 읽기 전용이며 쓰기/삭제 작업이 없습니다.

Install Server
F
license - not found
A
quality
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • gread

    An MCP server that gives your AI access to the source code and docs of all public github repos

  • saagarpatel.dev Portfolio

    Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.

  • hithereiamaliff-mcp-nextcloud

    A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/imshashwatsingh/github-assitant-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server