Skip to main content
Glama
deenesjakoruzh
halaprix

bd-explore

by halaprix
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

bd-explore

CI Python 3.10+ Zero dependencies License: MIT

beads 저장소에 질문하세요, codegraph explore가 코드베이스에 질문하는 방식과 동일하게: 한 번의 호출로 가장 관련성 높은 beads를 그대로 — 설명, 노트, 코멘트, 종료 사유 — 각 히트의 관계 이웃과 함께 출력 예산 내에서 반환합니다.

기존 bd CLI가 남긴 격차를 채웁니다: bd search는 제목만 검색하고, bd query는 구조화된 데이터만 검색하며, 노트, 코멘트, 종료 사유는 검색하지 않습니다 — 성숙한 저장소의 대부분 지식이 여기에 있습니다. bd memories도 색인됩니다 (일반 CLI는 메모리 본문을 잘라내지만, 이 도구는 전체를 반환합니다).

문서 사이트: https://halaprix.github.io/bd-explore/

$ bd-explore "why did we re-point SYRP status:open"

═══ SYRP-142 [OPEN · P1 · task · updated 2026-08-12]
    Re-point SYRP feed to the v2 oracle
    The v1 oracle staleness window regressed after the chain upgrade…
    COMMENT (ksz 2026-08-11):
    Decision: re-point rather than patch v1 — see close reason on SYRP-118.
    ── neighborhood ──
    blocked by: SYRP-139 — Oracle failover runbook [in_progress]
    child of: SYRP-100 — Oracle migration epic [in_progress]
    mentions: SYRP-118

주요 기능

  • 심층 축어 검색: 제목, 설명, 설계, 승인 기준, 노트, 작성자 코멘트(날짜 포함), 종료 사유, 메모리에 대한 전체 Porter-stemmed FTS5 검색.

  • 관계형 이웃 그래프: 1-홉 의존성 (blocks, blocked-by, parent-child, supersedes, discovered-from, related), 교차 산문 언급 참조, GitHub 이슈/PR 링크 (#NNN)를 표시합니다.

  • 전이적 영향 범위: 전이적 의존성 체인을 질의(--blast <id>)하여 코드를 건드리기 전에 차단자, 하류 종속자, 에픽 계층 구조를 확인합니다.

  • 내장 Stdio MCP 서버: 제로 의존성 JSON-RPC 2.0 stdio Model Context Protocol (MCP) 서버로, bd_explore 도구를 최신 AI 코딩 어시스턴트에 제공합니다.

  • 다중 대상 플랫폼 설치 프로그램: Claude Code, Gemini CLI, Antigravity IDE, OpenAI Codex, Cursor, AGENTS.md에 대한 자동 검색 및 설정.

  • Beads 영구 메모리 주입: beads 메모리를 자동으로 설정(bd remember --key bd-explore)하여 모든 bd prime 세션이 bd-explore 컨텍스트로 에이전트를 준비시킵니다.

  • 엄격한 출력 예산 설정: 출력 문자 예산(--budget 24000)으로 LLM 워크플로에서 컨텍스트 윈도우 폭발을 방지합니다.

  • 제로 런타임 의존성: 순수 Python 3.10+ 표준 라이브러리 (sqlite3, json, argparse).

Related MCP server: Veridge MCP Server

설치

독립형 셸 설치 프로그램

bd-explore를 ~/.local/bin에 설치하고 감지된 에이전트 플랫폼을 자동으로 구성합니다:

# From repository clone
./install.sh

# Standalone uninstall
./install.sh --uninstall

Python 패키지 설치

# Standard pip install
pip install .

# Editable install for development
pip install -e .

사용법

CLI 검색

# Free text search across all fields (porter-stemmed FTS)
bd-explore "why did we re-point SYRP"

# Compose field filters with free text (codegraph-style)
bd-explore "hash refresh status:open type:task priority:1"
bd-explore "swap oracle epic:rpm5"

# Target specific store or force reindex
bd-explore --store ~/Projects/my-project "auth refactor"
bd-explore --rebuild

# Control limits and output budget
bd-explore -n 3 --budget 16000 "database migration"

지원되는 필터

필터

구문 / 값

설명

status:

open, in_progress, closed, deferred, all

상태별 필터링 (all은 종료된 beads를 낮은 순위로 검색)

type:

bug, feature, task, epic, chore

이슈 유형별 필터링

priority:

0, 1, 2, 3, 4 (또는 P0..P4)

우선순위 레벨별 필터링

epic:

<id-or-suffix>

특정 에픽에 속한 이슈 필터링

id:

<id-or-substring>

ID로 이슈 매칭 (부분 문자열 / 접두사)

필터가 아닌 토큰(예: foo:bar)은 자동으로 자유 텍스트 검색으로 넘어갑니다. 팁: 검색 문자열에 공백, 필터 콜론, 또는 서브명령어와 일치하는 단어가 포함된 경우 따옴표로 묶으세요 (예: bd-explore "serve refactor").

전이적 영향 범위

모든 bead에 대한 전체 전이적 의존성 그래프를 계산합니다:

bd-explore --blast 9o32

출력:

  • 상류 차단자: 이 bead를 직접 또는 전이적으로 차단하는 모든 이슈.

  • 하류 차단됨: 이 bead를 직접 또는 전이적으로 기다리는 모든 이슈.

  • 에픽 계층: 직접 및 상위 에픽.

Stdio MCP 서버

bd-explore에는 에이전트 통합을 위한 내장 JSON-RPC 2.0 stdio MCP 서버가 포함되어 있습니다. 개행으로 구분된 JSON (NDJSON)과 HTTP 스타일 Content-Length: 헤더 프레이밍을 모두 지원합니다.

서버를 직접 실행:

bd-explore serve --mcp
# Or with explicit store:
bd-explore serve --mcp --store ~/Projects/my-project

MCP 도구: bd_explore

스키마와 함께 bd_explore 도구를 노출합니다:

  • query (문자열): 선택적 필드 필터가 있는 검색 쿼리 문자열 (status:open type:task).

  • blast (문자열): 전이적 영향 범위를 계산할 Bead ID.

  • limit (정수, 기본값 5): 최대 시드 bead 수.

  • budget (정수, 기본값 24000): 출력 문자 예산 상한.

  • store (문자열, 선택 사항): 명시적 저장소 경로 또는 리포지토리 디렉토리.

다중 대상 에이전트 설치 프로그램

bd-explore install은 설치된 AI 개발자 도구를 검색하고, MCP 구성을 추가하며, 마커 펜스로 둘러싸인 에이전트 가이드라인을 주입하고, beads 영구 메모리를 주입합니다.

# Interactive setup (prompts for targets and location)
bd-explore install

# Automated non-interactive batch install
bd-explore install --yes

# Install for specific targets and location
bd-explore install --targets claude,gemini,cursor --location global --auto-allow --yes

# Uninstall configurations
bd-explore uninstall --yes

# Print MCP configuration snippet without modifying files
bd-explore print-config claude
bd-explore print-config cursor

지원되는 플랫폼

플랫폼

MCP 구성

지침 및 규칙

Claude Code

~/.claude.json / .mcp.json

~/.claude/CLAUDE.md / CLAUDE.md

Gemini CLI / Antigravity CLI

~/.gemini/settings.json / .gemini/settings.json

~/.gemini/GEMINI.md / GEMINI.md

Antigravity IDE

~/.gemini/config/mcp_config.json

IDE 지침 / 작업공간 규칙

OpenAI Codex

~/.codex/config.toml

~/.codex/AGENTS.md

Cursor

~/.cursor/mcp.json / .cursor/mcp.json

.cursor/rules/bd-explore.mdc

일반 에이전트 규칙

—

~/.config/AGENTS.md / AGENTS.md

마커 펜스로 둘러싸인 지침

지침은 마커 펜스로 안전하게 주입되어 깔끔한 업데이트 및 제거가 가능합니다:

<!-- BD_EXPLORE_START -->
## bd-explore

In repositories with a beads store (a `.beads/` directory exists at the repo root), reach for `bd-explore` BEFORE searching raw files or relying only on `bd search`:

- **MCP tool** (when available): `bd_explore` answers questions about beads/issues/decisions/memories verbatim — description, notes, comments, close reason, plus relationship neighborhood under an output budget.
- **Shell** (always works): `bd-explore "<query>"` (e.g. `bd-explore "why did we re-point SYRP status:open"`, `bd-explore --blast <id>`).

If there is no `.beads/` directory, skip bd-explore.
<!-- BD_EXPLORE_END -->

색인되는 항목

내용

출처

비고

제목, 설명, 설계, 승인 기준

.beads/issues.jsonl

주요 이슈 내용

노트, 종료 사유

.beads/issues.jsonl

중요한 컨텍스트 및 사후 분석

작성자 코멘트

.beads/issues.jsonl

타임스탬프가 있는 대화 기록

전체 메모리 본문

bd memories --json

영구 메모리 레코드

명시적 의존성 엣지

dependencies 배열

blocks, parent-child, supersedes, related 등.

언급 엣지

산문 교차 참조

이슈 산문 전체에서 인용된 bead ID의 정규식 매칭 결과

GitHub 참조

산문 교차 참조

채굴된 #NNN 이슈 및 풀 리퀘스트 참조

설계 원칙

  1. 파생 가능하고 폐기 가능. .beads/issues.jsonl을 읽어(export.auto: true 필요) ~/.cache/bd-explore/ 아래 SQLite FTS5 인덱스로 변환하며, export가 변경되면 자동으로 재구성됩니다. beads 저장소는 유일한 진실 공급원으로 남으며, 캐시는 자유롭게 삭제할 수 있습니다.

  2. 오래됨은 일급 시민. 모든 히트는 [상태 · P<n> · 유형 · 업데이트 YYYY-MM-DD] 스탬프가 찍힙니다.

  3. 종료된 beads도 기본 포함. 기록이 가치의 대부분이며, 종료된 히트는 동등한 관련성에서 열린 것보다 낮은 순위를 가집니다. status:open으로 좁힐 수 있습니다.

  4. 컨텍스트 윈도우 친화적. 출력 문자 예산을 엄격하게 적용하여 에이전트 대화에 편안하게 맞춥니다.

아키텍처

탐색 파이프라인은 하나의 깊은 모듈 뒤에 있으며, 다른 모든 것은 이에 적응합니다.

              CLI (cli.py)              MCP server (mcp.py)
                   │  thin adapters: args / JSON-RPC  │
                   └──────────────┬───────────────────┘
                                  ▼
                      Explorer (explorer.py)
        explore(query, …) → str   ·   blast(id, …) → str
     owns store discovery, index freshness, connection
       lifetime, defaults/clamping, canonical errors
                   ┌──────────────┴───────────────────┐
                   ▼                                  ▼
          index.py (SQLite FTS5,             search.py (BM25 search,
          mention mining, cache)             hydrate → pure render)

  • explorer.py — 호출자가 필요한 유일한 인터페이스: explore() / blast() 입력, 형식화된 텍스트 출력, 실패 시 ExploreError 반환.

  • index.py — .beads/issues.jsonl과 bd memories를 파싱하여 파생된 SQLite FTS5 캐시로 만들며, export가 변경되면 원자적으로 재구성됩니다.

  • search.py — BM25 검색 및 쿼리 파싱; hydrate()는 이웃과 제목을 일괄 가져오고(총 두 개 쿼리), render()는 순수하며 모든 예산/잘라내기 로직을 소유합니다.

  • installer/ — 공통 설치/제거 인터페이스 뒤의 다중 대상 플랫폼 어댑터.

도메인 용어는 CONTEXT.md에 있으며, 리포지토리 규칙은 CLAUDE.md에 있습니다.

개발

# Run the full test suite (stdlib unittest — no test dependencies either)
PYTHONPATH=src python3 -m unittest discover tests -v

# Run one module / one case
PYTHONPATH=src python3 -m unittest tests.test_explorer
PYTHONPATH=src python3 -m unittest tests.test_render.TestRenderPure

# Editable install
pip install -e .

CI는 Linux와 macOS에서 Python 3.10–3.14에 걸쳐 테스트 스위트를 실행합니다. 릴리스 내역은 CHANGELOG.md를 참조하세요.

요구 사항

  • Python 3.10+

  • FTS5 가상 테이블을 지원하는 SQLite (공식 CPython 배포판에 포함)

라이선스

MIT License. 자세한 내용은 LICENSE를 참조하세요.

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
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.

Related MCP Servers

  • EzRAG MCP Server

    benbjurstrom
    A
    license
    -
    quality
    D
    maintenance
    Provides semantic search and keyword search over Obsidian notes, along with direct note retrieval, allowing external AI agents to query and access the vault.
    18
    BSD Zero Clause

  • recall

    tools-for-agents
    A
    license
    -
    quality
    B
    maintenance
    Enables agents to query across all their memory stores (brain, team, reading, code) in one call, returning a token-budgeted, ranked briefing with results interleaved from each source.
    MIT

  • AI Knowledge Base MCP Server

    Alpha-W0lf
    A
    license
    B
    quality
    B
    maintenance
    Provides read-only hybrid RAG search and discovery over a local-first AI knowledge corpus, enabling semantic and keyword search, browse, digest, and status tools.
    4
    MIT

View all related MCP servers

Related MCP Connectors

  • Dewey

    Agentic search over your Dewey document collections from any MCP-compatible client.

  • goldhold

    Persistent memory for AI agents. Search, store, and recall across sessions.

  • Leghis-smart-thinking

    Find relevant Smart‑Thinking memories fast. Fetch full entries by ID to get complete context. Spee…

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/halaprix/bd-explore'

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