Readwise MCP 서버

Readwise 라이브러리에 접근하고 상호작용하기 위한 MCP(모델 컨텍스트 프로토콜) 서버입니다.

특징

Readwise 라이브러리에서 하이라이트에 액세스하세요
자연어 쿼리를 사용하여 하이라이트 검색
도서관에서 책과 문서를 받으세요
Claude 및 기타 MCP 호환 어시스턴트와의 원활한 통합
하이라이트 분석을 위한 향상된 프롬프트 기능
운송 인식 로깅 시스템
강력한 오류 처리 및 검증
적절한 request_id 처리를 통한 MCP 프로토콜 준수
모니터링을 위한 상태 점검 엔드포인트
API 키 검증을 통한 개선된 설정 마법사

프로젝트 구조

이 저장소는 다음과 같은 주요 디렉토리로 구성되어 있습니다.

src/ : Readwise MCP 서버의 주요 소스 코드
test-scripts/ : MCP 서버 기능을 검증하기 위한 테스트 스크립트 및 유틸리티
- smart-mcp-test.sh : stdio 및 SSE 전송을 위한 주요 테스트 스크립트
- run-simple-server.sh : 간단한 MCP 서버를 실행하는 스크립트
- 전체 문서는 test-scripts/README.md 참조하세요.
예제/ : 예제 구현 및 코드 샘플
- examples/mcp-implementations/ : 기본 MCP 서버 구현
- examples/test-clients/ : 클라이언트 측 테스트 스크립트
- 전체 문서는 examples/README.md 참조하세요.
dist/ : 컴파일된 JavaScript 출력(생성됨)
scripts/ : 개발 및 테스트를 위한 유틸리티 스크립트

설치

지엑스피1

설정

서버를 사용하기 전에 Readwise API 키를 구성해야 합니다.

# Run the setup wizard
npm run setup

# Or start with the API key directly
readwise-mcp --api-key YOUR_API_KEY

https://readwise.io/access_token 에서 API 키를 받을 수 있습니다.

용법

CLI

# Start with stdio transport (default, for Claude Desktop)
readwise-mcp

# Start with SSE transport (for web-based integrations)
readwise-mcp --transport sse --port 3000

# Enable debug logging
readwise-mcp --debug

API

import { ReadwiseMCPServer } from 'readwise-mcp';

const server = new ReadwiseMCPServer(
  'YOUR_API_KEY',
  3000, // port
  logger,
  'sse' // transport
);

await server.start();

MCP Inspector로 테스트

이 프로젝트에는 MCP Inspector를 사용한 테스트 지원이 기본 제공됩니다. TypeScript 스크립트 또는 셸 스크립트를 사용하여 Inspector를 실행할 수 있습니다.

자동화된 테스트

모든 도구와 프롬프트를 검증하는 자동화된 테스트 모음을 실행합니다.

# Run automated inspector tests
npm run test-inspector

# Run in CI mode (exits with status code)
npm run test-inspector:ci

테스트 모음은 다음을 확인합니다.

서버 시작 및 연결
도구 가용성 및 응답
신속한 기능
오류 처리
응답 형식 준수

각 테스트는 자세한 출력과 합격/불합격 사례 요약을 제공합니다.

수동 테스트

쉘 스크립트 사용

# Test with stdio transport (default)
./scripts/inspector.sh

# Test with SSE transport
./scripts/inspector.sh -t sse -p 3001

# Enable debug mode
./scripts/inspector.sh -d

# Full options
./scripts/inspector.sh --transport sse --port 3001 --debug

TypeScript 스크립트 사용

# Test with stdio transport (default)
npm run inspector

# Test with SSE transport
npm run inspector -- -t sse -p 3001

# Enable debug mode
npm run inspector -- -d

# Full options
npm run inspector -- --transport sse --port 3001 --debug

사용 가능한 옵션

-t, --transport <type> : 전송 유형(stdio 또는 sse), 기본값: stdio
-p, --port <number> : SSE 전송을 위한 포트 번호, 기본값: 3001
-d, --debug : 디버그 모드 활성화

검사기 명령 예시

특정 도구 테스트:

./scripts/inspector.sh
> tool get-highlights --parameters '{"page": 1, "page_size": 10}'

프롬프트 테스트:

./scripts/inspector.sh
> prompt search-highlights --parameters '{"query": "python"}'

사용 가능한 도구와 프롬프트를 나열하세요.

./scripts/inspector.sh
> list tools
> list prompts

Readwise API 키 없이 테스트하기

Readwise API 키가 없거나 테스트에 실제 API 키를 사용하고 싶지 않은 경우 모의 테스트 기능을 사용할 수 있습니다.

npm run test-mock

이는 다음을 수행하는 테스트 스크립트를 실행합니다.

Readwise API의 모의 구현을 생성합니다.
이 모의 API로 MCP 서버를 설정합니다.
샘플 데이터로 다양한 엔드포인트를 테스트합니다.
실제 API 키가 필요하지 않고 서버 기능을 확인합니다.

모의 구현에는 다음이 포함됩니다.

샘플 책, 하이라이트 및 문서
현실적인 테스트를 위한 시뮬레이션된 네트워크 지연
오류 처리 테스트

사용 가능한 도구

get_highlights : Readwise 라이브러리에서 하이라이트 가져오기
get_books : Readwise 라이브러리에서 책을 가져옵니다
get_documents : Readwise 라이브러리에서 문서를 가져옵니다.
search_highlights : Readwise 라이브러리에서 하이라이트를 검색합니다.

사용 가능한 프롬프트

readwise_highlight : Readwise에서 하이라이트 처리
- 요약, 분석, 연결 찾기 및 질문 생성을 지원합니다.
- 강력한 오류 처리 및 매개변수 검증이 포함됩니다.
- 독자 친화적인 방식으로 하이라이트를 포맷합니다.
readwise_search : Readwise에서 하이라이트 검색 및 처리
- 소스 정보가 포함된 형식화된 검색 결과를 제공합니다.
- 사용자 친화적인 메시지로 API 오류를 우아하게 처리합니다.
- 필수 매개변수에 대한 검증이 포함됩니다.

최근 개선 사항

향상된 MCP 프로토콜 규정 준수

모든 응답에서 request_id의 적절한 처리
MCP 프로토콜 사양에 대한 수신 요청 검증
MCP 가이드라인을 따르는 일관된 오류 응답 형식

향상된 설정 경험

API 키 검증을 통한 대화형 설정 마법사
구성의 안전한 저장
문제 해결을 위한 자세한 오류 메시지

강력한 오류 처리

다양한 API 오류 조건에 대한 특정 오류 메시지
모든 도구와 프롬프트에서 일관된 오류 형식
프로토콜을 방해하지 않는 전송 인식 로깅

개발

# Build the project
npm run build

# Run tests
npm test

# Start in development mode with auto-reload
npm run dev:watch

# Lint code
npm run lint

특허

MIT