Skip to main content
Glama
deenesjakoruzh
SPARKIT-science

mcp-sparkit

Official
by SPARKIT-science
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

sparkit-mcp

SPARKIT용 MCP 서버 — Claude Desktop, Cursor, Claude Code 또는 기타 MCP 호환 클라이언트에서 과학 연구 에이전트를 호출하세요.

두 가지 도구가 제공됩니다:

  • research — 과학적 질문을 제출합니다. SPARKIT이 문헌을 검색하고 관련 논문을 읽은 뒤, 인용이 포함된 마크다운 보고서를 반환합니다. 작업이 완료될 때까지 대기(기본값 4분)한 후 전체 보고서를 인라인으로 반환합니다.

  • get_job_status — 이전에 제출된 작업을 ID로 가져옵니다. research가 작업 완료 전에 반환되었거나 이전 보고서를 다시 확인할 때 유용합니다.

설치

uv tool install sparkit-mcp

또는 pip 사용:

pip install sparkit-mcp

둘 다 sparkit-mcp 콘솔 스크립트를 설치합니다. (사전 릴리스: 첫 번째 PyPI 릴리스가 나올 때까지 uv tool install "git+https://github.com/SPARKIT-science/sparkit-mcp.git"을 사용하여 GitHub에서 직접 설치하세요.)

Related MCP server: pubmed-search-mcp

API 키 받기

  1. https://app.sparkit.science/signup 에서 가입하세요 (Try-it은 5회 쿼리에 $10이며, 구독은 월 $50부터 시작합니다).

  2. https://app.sparkit.science/keys 를 방문하여 키를 생성하세요.

  3. 키를 복사하세요 — 한 번만 표시됩니다.

MCP 클라이언트 구성

Claude Desktop

claude_desktop_config.json을 편집하세요:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

추가:

{
  "mcpServers": {
    "sparkit": {
      "command": "sparkit-mcp",
      "env": {
        "SPARKIT_API_KEY": "sk_sparkit_..."
      }
    }
  }
}

Claude Desktop을 다시 시작하세요. 채팅 입력창 옆의 도구 아이콘에 sparkit이 나타나야 합니다.

sparkit-mcp가 Claude Desktop의 PATH에 없는 경우(uv tool 사용 시 흔함), 절대 경로를 사용하세요:

"command": "/Users/you/.local/bin/sparkit-mcp"

(uv tool install 후 which sparkit-mcp로 경로를 찾으세요.)

Cursor

~/.cursor/mcp.json (또는 프로젝트 내 .cursor/mcp.json)을 편집하세요:

{
  "mcpServers": {
    "sparkit": {
      "command": "sparkit-mcp",
      "env": {
        "SPARKIT_API_KEY": "sk_sparkit_..."
      }
    }
  }
}

Cursor를 새로고침하세요 (Cmd+Shift+P → "Reload Window").

Claude Code

claude mcp add sparkit -e SPARKIT_API_KEY=sk_sparkit_... -- sparkit-mcp

사용해 보기

구성이 완료되면 LLM에게 다음과 같이 질문하세요:

SPARKIT을 사용하여 암에서 합성 치사 표적으로서의 WRNIP1 역할에 대한 최신 문헌을 찾아보세요.

LLM이 research를 호출합니다. 60~180초 정도 기다리면 인라인 인용과 번호가 매겨진 출처 목록이 포함된 마크다운 보고서가 제공됩니다.

구성

환경 변수

기본값

설명

SPARKIT_API_KEY

(필수)

https://app.sparkit.science/keys 에서 받은 Bearer 키.

SPARKIT_API_BASE

https://jlsteenwyk--sparkit-api-web.modal.run

API 기본 URL을 재정의합니다. 스테이징 또는 자체 호스팅 배포에 유용합니다.

SPARKIT_API_TIMEOUT_SECONDS

30

HTTP 요청당 타임아웃. research의 전체 대기 시간(max_wait_seconds)에는 영향을 주지 않습니다.

도구 참조

research(question, response_format?, include_citations?, max_wait_seconds?)

인수

유형

기본값

설명

question

string

—

과학적 질문. 필수. 구체적으로 작성하세요.

response_format

"full" 또는 "brief"

"full"

반환되는 마크다운 보고서의 길이.

include_citations

boolean

true

출처가 포함된 보고서를 원하면 true로 유지하세요.

max_wait_seconds

int (30-540)

240

작업 ID를 반환하고 폴링 지침을 제공하기 전까지 대기할 시간.

마크다운을 반환합니다. 타임아웃 시, LLM이 나중에 get_job_status를 호출할 수 있도록 job_id가 포함된 상태 줄을 반환합니다.

get_job_status(job_id)

작업이 완료되었으면 인용된 마크다운 보고서를 반환하고, 여전히 실행 중이면 상태 줄을, 그렇지 않으면 오류 메시지를 반환합니다.

문제 해결

인증 실패 — SPARKIT_API_KEY가 설정되지 않았거나 유효하지 않습니다. claude_desktop_config.json에 오타가 있는지 확인하고, 편집 후 Claude Desktop을 다시 시작하세요.

할당량 초과 — 월간 쿼리/Try-it 크레딧이 소진되었습니다. https://app.sparkit.science/billing 을 방문하세요.

Claude Desktop에 도구가 나타나지 않음 — Claude Desktop 로그를 확인하세요:

  • macOS: ~/Library/Logs/Claude/mcp-server-sparkit.log

  • Windows: %LOCALAPPDATA%\Claude\Logs\mcp-server-sparkit.log

가장 흔한 문제는 command: sparkit-mcp가 PATH에 없는 경우입니다. which sparkit-mcp로 확인한 절대 경로로 대체하세요.

작업 타임아웃 — max_wait_seconds의 최대값은 540초(9분)입니다. 매우 심도 있는 질문의 경우, 인라인으로 기다리지 말고 제출 후 get_job_status를 폴링하세요. SPARKIT은 자체 내부 제한을 초과하는 작업도 자동으로 취소합니다.

라이선스

MIT.

Available Tools

2 tools
get_job_statusA

Fetch the current status (and result if done) of a SPARKIT job.

Use this when research returned before the job finished, or to revisit a previous result by id.

Args: job_id: The id returned by a prior research call.

Returns the cited Markdown report if the job has completed, a status line if it's still running, or a failure message otherwise.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes return outcomes (completed report, running status, failure message). No annotations, but behavior is well-covered. Lacks explicit statement of non-destructiveness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise, front-loaded, each sentence adds value. Structured into purpose, usage, argument, returns. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all necessary aspects for a simple tool: usage, parameter, return behavior. Output schema exists, so description suffices.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains job_id as 'The id returned by a prior `research` call', adding meaning beyond schema's title 'Job Id'. Schema coverage 0%, so description compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Fetch the current status (and result if done) of a SPARKIT job', specifying verb and resource. Distinguishes from sibling 'research' by context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this when `research` returned before the job finished, or to revisit a previous result by id', providing clear when-to-use and alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

researchA

Submit a scientific question to the SPARKIT research agent.

SPARKIT searches the literature, reads relevant papers, and returns a cited Markdown report. Best for questions where a correct answer requires synthesizing across multiple primary sources.

Args: question: Free-text scientific question. Be specific — "Which kinases are upregulated in pancreatic cancer with evidence from human tissue?" works better than "tell me about pancreatic cancer." response_format: "full" (default) for a multi-paragraph Markdown report, or "brief" for a tighter summary. include_citations: Keep True (default) so the report is usable for downstream work; only set False if you specifically want unsourced prose. max_wait_seconds: How long to block waiting for the job before returning the job_id with instructions to poll via get_job_status. Default 240s (4 min). Range 30-540.

Returns the cited Markdown report on success. If the job is still running at the wait limit, returns the job_id and status so the caller can resume with get_job_status.

ParametersJSON Schema
NameRequiredDescriptionDefault
questionYes
response_formatNofull
include_citationsNo
max_wait_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description discloses key behaviors: async execution with timeout (max_wait_seconds), return types (inline report vs job_id), and parameter defaults. Could add rate limits or error handling, but overall thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured: concise opening, contextual paragraph, bullet-like Args section, and return value explanation. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers input, usage, return types, and sibling relationship. Missing explicit error scenarios, but output schema likely covers that. Overall very complete for a complex async tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining each parameter in detail: question specificity, response_format options, include_citations rationale, and max_wait_seconds range and purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool submits a scientific question to the SPARKIT research agent, which searches literature and returns a cited Markdown report. It distinguishes from sibling 'get_job_status' by describing async behavior and polling instructions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Best for questions where a correct answer requires synthesizing across multiple primary sources.' Provides context on when to use, and mentions alternative polling via get_job_status.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedget_job_status
    • First observedresearch
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.5/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: 'research' submits a scientific question and returns either a report or a job ID, while 'get_job_status' retrieves the status or result of a previously submitted job. There is no overlap in functionality.

Naming Consistency4/5

Both tool names use snake_case, but 'research' is a single-word noun while 'get_job_status' follows a verb_noun pattern. This minor inconsistency prevents a perfect score.

Tool Count4/5

With only two tools, the server covers the essential workflow of submitting a research job and checking its status. While minimal, the count is appropriate for the narrow scope of a scientific research agent.

Completeness3/5

The tool set covers the primary use case (submit and retrieve results), but lacks features like job listing, cancellation, or retry. For a simple agent this may suffice, but there are notable gaps in lifecycle management.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers