SSTIM MCP: Senses, Stimuli and Perception

SSTIM MCP: senses, stimuli, perception and research

Status: version 0.3.0 adds an explicitly authorized, GitHub-backed contribution workflow to the read-only knowledge tools. It supports the current MCP `2026-07-28` stateless protocol and legacy initialization-based clients (2025-11-25, 2025-06-18, 2024-11-05).

The adapter retrieves frozen SSTIM release data from the Concept Reference API. It is not an ontology write interface or hosted remote MCP endpoint. The four knowledge tools remain available without credentials. Four additional proposal tools can draft suggestions, browse GitHub review issues, and, only when an authorized operator has configured an Issues-write token and approved the exact public content, submit a GitHub issue for review. No tool changes canonical RDF or accepts scientific assertions as established.

Distribution and authorship

Primary author and responsible project: the SSTIM W3C Community Group. The canonical source is w3c-cg/sstim.

Acknowledgement: BioSynCare, for its contributions to and support of SSTIM's wider ecosystem. BioSynCare is not the authority behind the open SSTIM vocabulary.

Community Group work is not a W3C Recommendation or a W3C-endorsed product.

Install from npm (published)

`@sstim/mcp@0.3.0` is published on npm. It is listed as io.github.w3c-cg/sstim in the official MCP Registry, registered by the canonical W3C Community Group repository via OIDC.

With Node.js 20+ and a compatible stdio MCP client, set command npx and arguments ["--yes", "@sstim/mcp@0.3.0"]. The server needs no checkout or API token. For a smoke test, run it outside packages/sstim-mcp/: npm may resolve the local package there instead of the published executable.

cd /tmp

npx --yes @sstim/mcp@0.3.0

The command waits for protocol messages; silence is expected until the MCP client sends them. Pin the exact npm version for reproducibility. Run node packages/sstim-mcp/server.mjs from a checkout only for development.

Distribution and directory-listing status. Each npm tarball is immutable; later repository documentation edits reach npm's package README only with a future release.

Prerequisites

• Node.js 20+ on the machine where the AI client runs.
• SSTIM checkout only if developing the server. It is not needed for the published npm package.
• Network access to the read-only reference API (default below).
• An AI client with support for local stdio MCP servers.

For each local-checkout example below, replace /absolute/path/to/sstim/packages/sstim-mcp/server.mjs with the actual absolute path to this file. On Windows, use a path like C:/Users/you/sstim/packages/sstim-mcp/server.mjs and ensure node is in the launching application's PATH.

The server is launched by the AI client. Running it manually will appear idle because it waits for JSON-RPC messages on stdin. It must not emit human-readable logs to stdout.

What can an AI assistant do with SSTIM MCP?

For a hands-on tutorial with eight concrete AI prompts, prerequisites, tool usage and limits, see the SSTIM MCP manual chapter and the MCP examples cookbook.

Here are examples for users of Codex, Claude Code, GitHub Copilot, Cursor, Gemini and compatible Neovim plugins. Each task combines an AI assistant's ordinary reasoning and project access with *read-only released SSTIM data*:

These MCP tools do not perform automatic SHACL validation, execute a stimulation protocol, diagnose anything, or modify the ontology. Use Python sstim or JavaScript @sstim/core for data validation, and use the Workbench to explore or author reference patches.

Contribution workflow (since 0.3.0)

The new sstim_draft_contribution tool builds a structured, unreviewed issue proposal, with an explicit epistemic status. sstim_list_contributions and sstim_get_contribution retrieve public issue records and their actual state. sstim_submit_contribution creates a public GitHub Issue, but only if SSTIM_ENABLE_PUBLIC_SUBMISSIONS=1 is explicitly set by the operator and SSTIM_GITHUB_TOKEN is configured with appropriate GitHub Issues write access and approvedForPublicSubmission: true is supplied after the operator reviews the exact proposal. A local cooldown and fingerprint scan reduce accidental duplicates. This is not an unattended permission to submit private material.

Never put the token in a plugin manifest or conversation. Use the host's credential or environment management; no GitHub credential is bundled. Contributions are not automatically accepted; a closed GitHub issue is not necessarily an accepted scientific assertion.

Supported proposal kinds: correction, missing knowledge, scientific evidence, interoperability, research need and other. Relevant subjects may include sensory transduction, perception, sound or music-based practices, neuroscience, creative work and technological applications. SSTIM is not a comprehensive encyclopedia of these areas; gaps are valid reports. Sources are contributor-supplied and must be independently assessed.

Tools

Every tool except sstim_submit_contribution is read-only, and that one is disabled unless the operator opts in as described above. The feedback tool generates only a link with the selected public concept ID and label, without copying conversation text. The user reviews any issue and decides whether to publish it. No tool writes to the SSTIM ontology.

Configure your software

Choose one configuration appropriate to the AI client in use. They are not interchangeable. Sample files are in examples/.

1. VS Code: GitHub Copilot Chat (Agent mode)

Create or update .vscode/mcp.json in your project using the examples/vscode.mcp.json contents:

{

"servers": { "sstim": { "type": "stdio", "command": "npx", "args": ["--yes", "@sstim/mcp@0.3.0"] } } }

In VS Code run MCP: List Servers (or use MCP commands in the Command Palette), start sstim, then open GitHub Copilot Chat → Agent mode and enable the SSTIM tools in the tool picker.

This is VS Code's servers format, not the mcpServers format used by Cursor and Gemini. VS Code can also use a portable project-root .mcp.json, which has different keys; see its official MCP setup.

2. VS Code: OpenAI Codex extension / Codex CLI

Codex's IDE extension and CLI share ~/.codex/config.toml (or supported project-scoped .codex/config.toml). Append the contents of examples/codex.config.toml:

[mcp_servers.sstim]

command = "npx" args = ["--yes", "@sstim/mcp@0.3.0"]

Or configure the server via the Codex IDE extension: Settings → MCP servers → Add server → STDIO. Restart the extension if prompted. In the CLI, codex mcp list can show the configured servers. This configuration is separate from .vscode/mcp.json for Copilot Chat.

Reference: Codex MCP configuration.

3. VS Code: Claude Code extension / Claude Code CLI

Run in a terminal (using the same Claude Code installation as your extension):

claude mcp add --transport stdio --scope user sstim -- npx --yes @sstim/mcp@0.3.0

claude mcp get sstim

Then open Claude Code (CLI or VS Code extension) and check the /mcp menu to confirm the server is connected and tools are visible. The -- separator is important: arguments after it belong to npx, not to Claude's CLI. For a shared project installation instead of a personal user installation, consult the project's .mcp.json and approval rules.

Reference: Claude Code MCP setup.

4. Gemini CLI (including inside VS Code's terminal)

Add to your user ~/.gemini/settings.json or project .gemini/settings.json:

{

"mcpServers": { "sstim": { "command": "npx", "args": ["--yes", "@sstim/mcp@0.3.0"] } } }

See examples/gemini.settings.json. Alternatively use:

gemini mcp add -s user sstim npx --yes @sstim/mcp@0.3.0

Open Gemini CLI and use /mcp to inspect connectivity and exposed tools.

Gemini CLI is not the same product as the Gemini Code Assist VS Code extension. This configuration applies to the CLI; support for an extension must be verified against that extension's own settings. Reference: Gemini CLI MCP.

5. Cursor

Create a project .cursor/mcp.json, or ~/.cursor/mcp.json globally, with the contents of examples/cursor.mcp.json:

{

"mcpServers": { "sstim": { "command": "npx", "args": ["--yes", "@sstim/mcp@0.3.0"] } } }

Open Cursor Settings → Tools & MCP and verify the server is connected. Ask Cursor Agent to use sstim_search_concepts.

Reference: Cursor MCP documentation.

6. Neovim with CodeCompanion.nvim

Neovim does not supply an AI/MCP client merely by being installed. If you use CodeCompanion.nvim, add