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互換クライアントから科学研究エージェントを呼び出すことができます。

以下の2つのツールが公開されています：

  • research — 科学的な質問を送信します。SPARKITが文献を検索し、関連する論文を読み込み、引用付きのMarkdownレポートを返します。ジョブが完了するまで待機し（デフォルト4分）、レポート全文をインラインで返します。

  • get_job_status — 以前に送信したジョブをIDで取得します。researchがジョブ完了前に戻ってきた場合や、過去のレポートを再確認したい場合に便利です。

インストール

uv tool install sparkit-mcp

またはpipを使用する場合：

pip install sparkit-mcp

いずれの方法でも sparkit-mcp コンソールスクリプトがインストールされます。（プレリリース版：最初のPyPIリリースまでは、GitHubから直接 uv tool install "git+https://github.com/SPARKIT-science/sparkit-mcp.git" でインストールしてください。）

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に次のように尋ねてみてください：

Use SPARKIT to look up the most recent literature on the role of WRNIP1 as a synthetic-lethal target in cancer.

LLMが research を呼び出します。60〜180秒ほど待つと、インライン引用と番号付きのソースリストを含むMarkdownレポートが返されます。

設定

環境変数

デフォルト

説明

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"

返されるMarkdownレポートの長さ。

include_citations

boolean

true

ソース付きレポートにする場合は true を維持してください。

max_wait_seconds

int (30-540)

240

ジョブIDを返してポーリングを指示するまでに待機する時間。

Markdownを返します。タイムアウトした場合は、LLMが後で get_job_status を呼び出せるようにジョブIDを含むステータス行を返します。

get_job_status(job_id)

ジョブが完了していれば引用付きのMarkdownレポートを、まだ実行中であればステータス行を、それ以外の場合はエラーメッセージを返します。

トラブルシューティング

Authentication failed — SPARKIT_API_KEY が設定されていないか、無効です。claude_desktop_config.json に誤字がないか確認し、編集後にClaude Desktopを再起動してください。

Quota exhausted — 月間クエリ数またはTry-itクレジットが上限に達しています。https://app.sparkit.science/billing を確認してください。

Tool isn't appearing in 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 で確認した絶対パスに置き換えてください。

Job times out — 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