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/[email protected] 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/[email protected]"]. 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/[email protected]

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:

Task	What to ask for	What SSTIM MCP contributes
Code/data schema alignment	"Inspect my session JSON and map frequency, technique, channels and session fields to SSTIM"	Canonical term IRIs and module/release provenance; not an automatically validated mapping
Research terminology review	"Compare meanings of binaural and isochronous techniques without conflating stimulation with EEG bands"	Definitions and related concept links
Version migration	"Retrieve this exact IRI in 0.18.0 and 0.19.0; report asserted differences"	Version-pinned details, deprecation and mappings
Cross-ontology interoperability	"List external alignments for this term, including the precise SKOS relation"	Mapped external IRIs and relation strengths
Codebase audit	"Find fields in my code matching published SSTIM properties; flag unknown ones"	Stable identifiers; human review of inferred matches
Write scientific documentation	"Explain these terms with source references; distinguish evidence from labels"	Released definitions, source module and hashes
Correct the standard	"Find this term or gap and prepare a link for me to submit a correction"	A user-reviewed Contribution Bridge link, not a submission
Repeatable research	"Use only release 0.19.0 for all SSTIM terms cited in this protocol"	Release-qualified records for reproducibility

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

Tool	Result
sstim_list_releases	Supported frozen releases and latest available version
sstim_search_concepts	Search terms by IRI/CURIE, labels, alternatives or definition
sstim_get_concept	Retrieve exact term, definitions, declared relationships, source provenance
sstim_prepare_feedback	User-facing Contribution Bridge link; nothing is submitted
sstim_draft_contribution	Structured, unreviewed proposal text; nothing is submitted
sstim_list_contributions	Recent public contribution issues and their GitHub state
sstim_get_contribution	One public contribution issue, its unverified text and state
sstim_submit_contribution	Public GitHub issue for review; refused unless the operator enabled submissions

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/[email protected]"]
    }
  }
}

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/[email protected]"]

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/[email protected]
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/[email protected]"]
    }
  }
}

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

gemini mcp add -s user sstim npx --yes @sstim/[email protected]

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/[email protected]"]
    }
  }
}

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 this to its setup (or integrate the mcp table into existing config):

require("codecompanion").setup({
  mcp = {
    servers = {
      sstim = {
        cmd = { "npx", "--yes", "@sstim/[email protected]" },
      },
    },
    opts = {
      default_servers = { "sstim" },
    },
  },
})

See examples/neovim-codecompanion.lua. Open a CodeCompanion chat and access MCP tools using the @mcp: tool group or the /mcp picker, depending on your CodeCompanion version. The plugin's MCP client currently supports the older 2025-11-25 handshake, which this server continues to accept.

For classic Vim, no built-in MCP client is assumed. You can use the Claude Code, Codex, or Gemini CLI configuration above in a terminal inside or outside Vim; do not paste Neovim Lua into a traditional .vimrc.

Verify the installation

After configuring your chosen client, ask:

Use the SSTIM MCP tools to list the current released version, search for “binaural”, and explain one matched concept using its canonical IRI and source provenance. Compare the results for v0.18.0 and v0.19.0 if applicable.

The search tools may be automatically chosen by the agent, but whether a tool is called depends on client settings and model behavior. You can also inspect the tool inventory in your host's MCP panel.

For tests inside this repository:

npm test -- --run packages/sstim-mcp/mcp.test.mjs
npm run check
npm run build

The tests exercise mocked API data, legacy and modern MCP handshakes, stdio framing, and editor-config example syntax. They do not certify interoperability with every named editor release.

Protocol versions and constraints

2026-07-28 is the current MCP protocol revision. Unlike 2025-11-25, which negotiates a process-scoped session via initialize / notifications/initialized, the new revision uses per-request metadata. This server implements both paths:

• Modern clients: server/discover advertises 2026-07-28, tools are usable without initialize, and every request carries params._meta["io.modelcontextprotocol/protocolVersion"] and params._meta["io.modelcontextprotocol/clientCapabilities"]. Results declare resultType: "complete" and server identity metadata.
• Older clients: continue using the legacy initialize handshake and legacy response structure. Supporting this version remains important for real installed clients, including some Neovim plugins.

The modern revision does not mean the server must be remote: stdio remains a defined transport. There is currently no Streamable HTTP endpoint for SSTIM MCP; remote ChatGPT connectors would require a separate deployment.

Protocol references: MCP 2026-07-28 versioning, stdio transport, discovery.

The latest frozen release comes from API discovery, not from a hard-coded runtime constant. At the time of this update it is v0.19.0; the separately maintained development line is v0.20.0-dev. For repeatable research use an explicit frozen release in tool arguments.

Operational limits: read-only ontology catalog; up to 20 search results; no hosted ?q= search; no live ontology inference, adjudication of scientific disputes, or guaranteed clinical meaning. The default reference URL is https://w3c-cg.github.io/sstim/api/v1/. An operator can override it with SSTIM_MCP_API_BASE, using HTTPS or loopback HTTP for testing. A per-process cache keeps repeated requests local until restart. Outputs retain term IRIs, release identity and source links.