de en es ja ko ru zh

bd-explore

Name: bd-explore
Author: halaprix

by halaprix

Overview Schema Source Related Servers Discussions Admin

Python

Local

bd-explore

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: recall

설치

독립형 셸 설치 프로그램

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` 이슈 및 풀 리퀘스트 참조

설계 원칙

파생 가능하고 폐기 가능. .beads/issues.jsonl을 읽어(export.auto: true 필요) ~/.cache/bd-explore/ 아래 SQLite FTS5 인덱스로 변환하며, export가 변경되면 자동으로 재구성됩니다. beads 저장소는 유일한 진실 공급원으로 남으며, 캐시는 자유롭게 삭제할 수 있습니다.
오래됨은 일급 시민. 모든 히트는 [상태 · P<n> · 유형 · 업데이트 YYYY-MM-DD] 스탬프가 찍힙니다.
종료된 beads도 기본 포함. 기록이 가치의 대부분이며, 종료된 히트는 동등한 관련성에서 열린 것보다 낮은 순위를 가집니다. status:open으로 좁힐 수 있습니다.
컨텍스트 윈도우 친화적. 출력 문자 예산을 엄격하게 적용하여 에이전트 대화에 편안하게 맞춥니다.

아키텍처

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

              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 deployed

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

KlaaroOAuth
ai.klaaro
Query Klaaro datasets, documents, and extracted records from any agent.
Search Databases RAG Systems
1
Santismm Knowledge — Harness Engineering, Agentic AI & Governance A
com.santismm
Query core AI knowledge, essays, executable Labs, Homeric data and epistemic claims.
Knowledge & Memory Research & Data Education & Learning Tools
3011
Knowledge for Agents A
com.knowledgeforagents
Search real problems, solutions, failed approaches and observed outcomes shared by AI agents.
Search Knowledge & Memory RAG Systems
41
Monolithos
ai.monolithos
Recall authorized Vault notes with keyword and hybrid search, original excerpts, and source paths.
1

Related MCP Servers

EzRAG MCP Server
RAG Systems Search Note Taking
benbjurstrom
A
license
Not graded
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.
Updated 9 months ago (2025-12-29 17:39 UTC)
19
BSD Zero Clause
recall
Knowledge & Memory Search
tools-for-agents
A
license
Not graded
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.
Updated 14 days ago (2026-09-27 08:59 UTC)
14 npm
MIT
bd-graph MCP Server
Knowledge & Memory Databases
halaprix
A
license
Not graded
quality
C
maintenance
Enables coding agents to query a temporal knowledge graph derived from a beads issue tracker via read-only Cypher queries, exposing current rules, supersession chains, and provenance without LLM API keys.
Updated 2 months ago (2026-08-01 09:39 UTC)
MIT
Codex Jev
RAG Systems Code Analysis Developer Tools
Hyper-AI-Lab
A
license
Not graded
quality
C
maintenance
Enables coding agents to discover, optionally rank, and exactly read bounded source-addressed evidence from large repositories and noisy logs, with local-only privacy controls and quota-aware recovery.
Updated 2 days ago (2026-10-08 14:36 UTC)
1
MIT

bd-explore

주요 기능

설치

독립형 셸 설치 프로그램

Python 패키지 설치

사용법

CLI 검색

지원되는 필터

전이적 영향 범위

Stdio MCP 서버

MCP 도구: bd_explore

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

지원되는 플랫폼

마커 펜스로 둘러싸인 지침

색인되는 항목

설계 원칙

아키텍처

개발

요구 사항

라이선스

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

EzRAG MCP Server

recall

bd-graph MCP Server

Codex Jev

MCP 도구: `bd_explore`