Sentinel-IR-MCP 0.2.2: Less Config Archaeology, More Useful Context

Sentinel-IR-MCP 0.2.2: Less Config Archaeology, More Useful Context

MCP is supposed to make tools easier to connect to AI assistants.

So why can connecting one useful tool still involve hunting for JSON files, editing configuration by hand, restarting applications, and wondering whether the server is actually working?

Sentinel-IR-MCP 0.2.2 introduces three new commands: "setup", "doctor", and "guide".

The goal is straightforward: make connecting Sentinel-IR to an MCP client less fragile, make common problems easier to diagnose, and give an AI agent clearer instructions for using the tools correctly.

But this is not just an installation story.

Sentinel-IR-MCP gives AI agents a compact structural view of JavaScript and TypeScript code. Instead of starting by consuming entire files, an agent can inspect a project's structure, prioritize relevant files, and retrieve more detailed facts when needed.

This release makes that workflow easier to connect and verify.

Release: "Sentinel-IR-MCP v0.2.2 on GitLab" (https://gitlab.com/jakubrojicek11/sentinel-ir-mcp/-/tree/v0.2.2?ref_type=tags)

Package: "[email protected] on npm" (https://www.npmjs.com/package/sentinel-ir-mcp/v/0.2.2)

Choose your depth

• 30 seconds: What changed and why it matters.
• 10 minutes: The human version. What the tool does, how to use it, and what it means in practice.
• 20–30 minutes: The developer deep dive. CLI behavior, MCP handshakes, filesystem boundaries, analysis output, tests, limitations, and reproduction.

You can read the first section, decide whether this project is relevant to you, and leave. Or keep digging. No mandatory boss fight. 🎮

Part 1: The first 30 seconds

What is new in v0.2.2?

Three commands:

Command| Purpose
"setup"| Connect Sentinel-IR to a supported MCP client with a guided configuration process.
"doctor"| Check the package, configuration and an actual MCP server connection.
"guide"| Print instructions an AI agent can follow when analyzing a project.

Try the quick setup from your project directory:

npx -y [email protected] setup --client cursor

Then, after restarting or refreshing the client:

npx -y [email protected] doctor --client cursor

For usage instructions:

npx -y [email protected] guide

These commands use the "0.2.x" release line, rather than pinning the example to one exact patch version.

What has not changed? The three core MCP tools remain "analyze_code", "analyze_file", and "analyze_directory". The structural analysis is the foundation; v0.2.2 makes it easier to connect and diagnose.

If you remember only one thing:

«v0.2.2 is about reducing setup friction and making the connection easier to inspect, not claiming that the code analyzer suddenly understands every possible program.»

Now let's make that useful even if you have never written a line of JavaScript.

Part 2: The 10-minute version for everyone else

1. Imagine asking an AI to understand a whole project

Suppose you ask an AI coding assistant:

"Can you inspect this repository and tell me which files I should look at first?"

A repository may contain hundreds or thousands of files. Reading all of them immediately can be slow, expensive in model context, and unnecessary.

A better first question is:

Can we give the AI a map before asking it to walk every street?

That is the central idea behind Sentinel-IR.

It analyzes JavaScript and TypeScript code and returns a compact structural representation. Depending on the source, the result can include facts about:

• Imports and exports.
• Recognized risky capabilities, such as dynamic evaluation or process execution.
• Network, filesystem and environment-related operations.
• Routes and other structural facts.
• Analysis status and whether the result is incomplete.

An agent can first inspect a directory, prioritize files, and then request a more detailed analysis of the files that matter.

This is not the same as sending a smaller copy of every line. The point is to provide selected structural facts rather than raw source by default.

And an important distinction: a compact structural map is not a guarantee that the code is safe. It is a way to focus investigation.

1. What MCP contributes

MCP stands for Model Context Protocol. It provides a common way for an AI application to communicate with tools supplied by another program.

In this project, the pieces look like this:

You
|
v
AI client
(Claude Desktop, Cursor, Windsurf, etc.)
|
| MCP
v
Sentinel-IR-MCP
|
v
Sentinel-IR
|
v
Compact structural facts about the code

The AI client can request a tool call. Sentinel-IR-MCP exposes the analysis tools through MCP, and Sentinel-IR performs the underlying analysis.

This separation matters because the model does not need to implement the parser itself for every conversation. It can request structured analysis through a defined interface.

MCP does not magically make every AI application compatible with every tool. The client still needs to support the transport and the relevant configuration or installation mechanism.

That brings us to the unglamorous part.

1. The configuration problem

Before v0.2.2, the standard setup route involved adding a server entry to the relevant client configuration.

For example, a Cursor project configuration could contain:

{
"mcpServers": {
"sentinel-ir": {
"command": "npx",
"args": [
"-y",
"[email protected]",
"${workspaceFolder}"
]
}
}
}

The JSON is not especially complicated.

The difficult part is knowing which file to edit, which path to use, what the client expects, whether the configuration already contains other servers, and whether the result actually works.

For someone comfortable with development environments, this may be a minor nuisance.

For a new developer, it can become a wall between "I want to try this tool" and "I have no idea why nothing is happening."

The new CLI is designed to reduce that wall.

1. "setup": connect without blindly rewriting your configuration

Run:

npx -y [email protected] setup

Without "--client", the command offers a client selection when running interactively.

Or specify a client directly:

npx -y [email protected] setup --client cursor

The supported client names include:

• "cursor"
• "windsurf"
• "claude-desktop"
• "vscode"
• "claude-code"

The setup behavior depends on the client.

For file-based configuration, it shows the planned change and asks for confirmation before writing. You can also preview the operation:

npx -y [email protected] setup --client cursor --dry-run

Or explicitly approve a non-interactive operation:

npx -y [email protected] setup --client cursor --yes

The goal is not to take over the client's entire configuration. Setup adds or replaces the "sentinel-ir" entry while preserving unrelated servers and other configuration fields.

It also has several safety measures:

• Existing configuration is backed up before being changed.
• Writing uses a temporary file followed by a rename.
• Invalid JSON is rejected without modifying the original.
• Running setup again with the same configuration should not produce another content change.
• The selected project directory is validated.

For VS Code and Claude Code, setup prints the client's own installation command instead of pretending that both applications use the same file-based configuration mechanism.

That last point is important. A guided setup should respect the client, not force every client into one generic template.

1. "doctor": don't just hope the connection works

Configuration can look correct and still fail in practice.

Run:

npx -y [email protected] doctor --client cursor

The command checks the Node.js version, package information, applicable client configuration, the server entry and referenced folders. It then starts its own Sentinel-IR-MCP server process, performs an MCP handshake, verifies the expected tools and calls "analyze_directory" with a limit of one file.

That is more useful than checking whether a JSON file merely exists.

There is an important limitation, however: "doctor" does not execute the exact command stored in the client's configuration. It starts its own server process using the relevant folders.

Therefore, a successful result is evidence that the package can start and serve its tools through MCP. It is not a complete end-to-end test of the client application's own launch behavior.

For command-managed clients such as VS Code and Claude Code, their server lists also need to be checked through their own mechanisms.

A real client-side tool call is still the final practical check.

1. "guide": help the AI use the tools in the right order

There is a second problem after installation.

Even when an agent has access to tools, it may choose an inefficient workflow. It might read files in the wrong order, ignore incomplete results, or assume that a low reported risk means a file is safe.

Run:

npx -y [email protected] guide

The command prints instructions for using the tools. These instructions can be added to an "AGENTS.md" file or to client-specific agent rules.

The recommended workflow is:

1. Start with "analyze_directory".
2. Check incomplete and unreadable results.
3. Prioritize relevant files.
4. Use "analyze_file" for a detailed structural summary.
5. Read raw source only when it is needed for investigation or a change.

This is a small but meaningful design choice: an available tool is not the same thing as a well-used tool.

The guide tries to make the intended workflow explicit instead of leaving every agent to rediscover it.

1. Is this a security tool?

It can help identify structural risk signals, but it is not a comprehensive security scanner.

A low risk result means that the analyzer did not recognize certain risky patterns in the analyzed source. It does not prove the program is harmless.

Dynamic behavior can be difficult to recognize statically. Unsupported syntax or parsing problems can also limit the result. That is why analysis status matters.

Sentinel-IR-MCP also restricts which files it reads and how it receives access to project folders. The server is designed to read source files without modifying or executing them.

Those are useful boundaries, but they do not remove every risk associated with using AI tools.

For example, the structural representation can still contain identifiers and some literals from the source code. Also, the AI client may send tool results to its configured model provider. Local file analysis should not be confused with a guarantee that all information remains local throughout the entire AI workflow.

The correct approach is to inspect the boundaries and understand what information is returned.

1. Who might find v0.2.2 useful?

Developers using MCP clients: less manual configuration work and a more concrete diagnostic command.

People experimenting with AI coding agents: a way to expose structural code analysis without building their own integration layer.

Teams working with larger repositories: a workflow for triaging files before requesting deeper analysis.

Developers who care about repeatability: clearer setup behavior, more explicit error handling and automated tests for common failure cases.

If you only need a general chatbot, this package is probably not relevant to you.

If you want an AI coding agent to inspect JavaScript or TypeScript repositories through an MCP interface, it is worth a look.

Part 3: The developer deep dive

The next sections cover what changed, how the commands behave, the analysis interface, the guardrails, and what has and has not been verified.

1. Version history: what belongs to 0.2.2?

The easiest way to misunderstand a release is to attribute every existing feature to the newest version.

Here is the distinction.

Capability| Status
"analyze_code", "analyze_file", "analyze_directory"| Existing core tools, retained in 0.2.2
TypeScript support, including the documented TSX variants| Introduced in the 0.2.0 line, not new in 0.2.2
Structural IR and risk signals| Existing Sentinel-IR functionality
Explicit "analysisStatus" and incomplete-result handling| Already documented in 0.2.0/0.2.1
"setup" CLI command| New in 0.2.2
"doctor" CLI command| New in 0.2.2
"guide" CLI command| New in 0.2.2
Client-aware configuration handling and setup safety checks| Added as part of the 0.2.2 Easy Connect work

The tag comparison between "v0.2.1 and v0.2.2" (https://gitlab.com/jakubrojicek11/sentinel-ir-mcp/-/compare/v0.2.1...v0.2.2) documents the release as the addition of setup, doctor, and guide commands.

The analyzer itself remains the underlying engine. The new work is the integration and usability layer around it.

1. Runtime requirements and installation

The package requires Node.js 20 or newer.

You can start the CLI through "npx" without globally installing the package:

npx -y [email protected] --help

Check the version resolved by npm:

npx -y [email protected] --version

Then connect it to a client:

npx -y [email protected] setup --client cursor

One detail matters for reproducibility: "[email protected]" selects the 0.2.x version line, not the exact "0.2.2" patch. This is intentional in the setup instructions, which aim to receive compatible fixes without automatically moving to a new major version.

Also, "npx" may need network access to download the package on first use. This is separate from the MCP server's runtime behavior. The server itself is designed not to open network connections while analyzing source files.

1. What does setup actually promise?

The goal is to make the operation predictable.

Project scope

The setup code validates the project directory and refuses to grant access to an entire disk or the user's whole home folder.

For example, this should be rejected:

npx -y [email protected] setup \
--client cursor \
--project "$HOME"

Use a specific project directory instead:

npx -y [email protected] setup \
--client cursor \
--project ./my-project

The exact path syntax depends on the shell and operating system.

Preview before writing

npx -y [email protected] setup \
--client cursor \
--project ./my-project \
--dry-run

This previews the planned configuration and writes nothing.

Explicit non-interactive approval

npx -y [email protected] setup \
--client cursor \
--project ./my-project \
--yes

"--yes" is a deliberate approval to apply the configuration change. It should not be confused with a blanket grant of filesystem permissions to the server.

Preserve existing settings

The implementation plans the change to the "sentinel-ir" server entry rather than replacing the entire MCP configuration.

If the existing configuration is invalid JSON, setup reports the problem instead of silently overwriting it.

When a file is changed, a timestamped backup is created first. The new content is written through a temporary file and then renamed into place.

These measures reduce the chance of destroying unrelated client configuration. They do not eliminate every possible filesystem failure, concurrent write or client-specific edge case.

1. Client behavior is not identical

Different clients manage MCP servers differently.

The current implementation handles the following cases:

Client| Setup behavior
Cursor| Supports project configuration and a global configuration option
Windsurf| Targets its MCP configuration file
Claude Desktop| Handles documented macOS and Windows configuration locations; another location can be supplied explicitly
VS Code| Prints the client's own MCP installation command
Claude Code| Prints the client's own MCP installation command

For Cursor, the project configuration uses "${workspaceFolder}". A global Cursor configuration instead uses the absolute project path.

For VS Code and Claude Code, setup does not write a generic configuration file. It prints a command appropriate to the client.

One-click links for Cursor and VS Code are also provided in the README. The release documentation says those links were generated and decoded in tests, but not clicked through in the real applications. That distinction matters when describing their verification status.

1. What does "doctor" check under the hood?

The doctor implementation does more than parse a config file.

At a high level, it:

1. Checks that Node.js meets the minimum supported version.
2. Reports the installed MCP package and the underlying "sentinel-ir" version.
3. Looks for the applicable client configuration and its "sentinel-ir" entry.
4. Checks whether the referenced project folders exist.
5. Starts its own server process.
6. Connects using the MCP SDK over standard input/output.
7. Checks that the expected tools are exposed.
8. Calls "analyze_directory" with a limit of one file when a folder is available.
9. Returns a status and an exit code.

You can request JSON output for a machine-readable result:

npx -y [email protected] doctor \
--client cursor \
--json

This can be useful in scripts or when another tool needs to inspect the result.

The important boundary

The implementation deliberately does not run the exact command saved in the client configuration.

Why does this matter?

Imagine the configuration contains a command that points to an outdated executable. Doctor can verify the configuration structure and run its own server successfully, but that is not the same as executing the client's stored command exactly as the client would.

The distinction is between:

• Package and protocol verification: the package can start, expose the expected tools and respond to a call.
• Client integration verification: the actual application recognizes the server and successfully makes a tool call through its own configuration.

The first is automated by doctor. The second still needs a client-side check.

This is not a reason to dismiss doctor. It is a reason to describe its guarantees precisely.

1. The core MCP interface

The release exposes three tools.

"analyze_code"

Analyze source text passed to the tool. The caller can optionally provide a target filename or an explicit language selection.

{
"code": "export function greet(name) { return Hello ${name}; }",
"target": "greeting.js"
}

This is useful when the source is already available to the AI client.

"analyze_file"

Analyze a single file within the allowed directories.

{
"path": "src/server.js"
}

The server does not treat an arbitrary path as permission to open any file on the machine. Paths are checked against the permitted folders.

"analyze_directory"

Analyze a directory and return a per-file structural summary.

{
"path": "src",
"max_files": 20,
"recursive": true
}

The documented default file limit is 50, with a maximum of 500. Results include risk and status summaries, and are ordered to help prioritize inspection.

The response also identifies relevant skipped or incomplete files. These are not details to ignore: if analysis did not finish, a low risk value is not evidence that the source is safe.

1. What does the structural representation look like?

Consider a small JavaScript file that uses "eval" and "child_process".

A compact result can expose facts such as:

{
"analysisStatus": "complete",
"world": {
"risk": "critical",
"confidence": 0.75
},
"forbidden": [
"eval",
"child_process",
"process_spawn"
],
"facts": {
"ast": true,
"imports": ["child_process"],
"operations": [
"dynamicEval",
"processSpawn",
"childProcess"
],
"dangerous": [
"eval",
"child_process",
"process_spawn"
]
}
}

This is a shortened illustration of the published README's example, not a complete schema contract for every source file.

It gives the agent signals that may help it decide which files deserve more attention.

The agent can then retrieve a file-level structural result or inspect the original source when it needs evidence for a specific claim or code change.

The important point is not that every result contains the same fields. It is that the analyzer provides structured facts that are easier to process consistently than a free-form explanation alone.

1. Read-only behavior and filesystem boundaries

The MCP server is designed to read source files, not modify or execute them.

The documented runtime boundaries include:

• Only the supported JavaScript and TypeScript file extensions are analyzed.
• The maximum file size defaults to 1 MiB.
• File access is limited to explicitly allowed folders or roots supplied by the client.
• Resolved paths must remain inside those allowed folders.
• Symlinks pointing outside those folders are refused.
• Directory analysis skips "node_modules", ".git", hidden folders and symlinks.
• Directory analysis stops at the configured file limit and reports truncation.

The core server does not write files, execute commands, or open network connections.

Setup is a separate command with a separate responsibility: it can modify the applicable client configuration after the planned change has been approved. Doctor starts its own local server process to test the connection.

This separation reduces the server's operational scope.

It is still important to review the actual code and permissions before using any tool against a sensitive repository. "Read-only" describes the server's intended operations; it is not a universal security certification of the whole AI environment.

1. Compact context is useful, but it is not magic

One reason to use structural facts is that the agent may not need the full source of every file for the first stage of an investigation.

The README records an example measurement using "[email protected]" with the "o200k_base" encoding, analyzing files from the published "[email protected]" library.

Sample file| Raw tokens| IR tokens
"src/ast-facts.js"| 8,439| 120
"src/sentinel-ir.js"| 2,084| 133
"src/tree-parser.js"| 891| 121
"examples/basic.js"| 150| 120
All four files| 11,564| 317

For these particular four files, the measured total falls from 11,564 tokens to 317, a reduction of about 97.3%.

That number is deliberately narrow.

These are sample measurements, not a universal guarantee for arbitrary repositories, every model or every task. Tokenizers differ. Small files can be close to the minimum useful structural representation, so replacing a small source file with IR may save little or nothing.

The purpose is to let the agent decide where full source is worth the additional context.

And to be precise: the measurement describes the structural analysis approach already present in the project. It is not a new benchmark introduced by v0.2.2.

1. Analysis status is a first-class fact

A risk classification without analysis status can be misleading.

Consider two files:

File A: analysis complete, no recognized dangerous pattern
File B: analysis incomplete, no recognized dangerous pattern

Those are not equivalent results.

The second file may contain unsupported syntax, parsing problems or other behavior that the analyzer did not fully inspect.

Sentinel-IR exposes "analysisStatus", and directory analysis reports incomplete and unreadable files. The workflow should inspect those fields before treating the risk ranking as a basis for action.

The agent instructions generated by "guide" reinforce this order:

1. Analyze the directory.
2. Check incomplete and unreadable results.
3. Prioritize relevant files.
4. Analyze individual files in more detail.
5. Read raw source where needed.

This is a small but useful example of making an intended workflow explicit in the tool interface and its usage instructions.

1. MCP output is still data, not authority

Structural IR can reduce how much source content reaches the model through the analysis tool. In particular, comments, string bodies and function bodies are not copied into the structural representation.

That can reduce the prompt-injection surface compared with passing complete files through this interface.

It does not eliminate prompt injection.

The IR can still contain identifiers and some literals, including route paths, module names, export names and environment variable names. Those values originate in the code and should be treated as untrusted data, not as instructions.

The receiving AI client may also expose tool results to a remote model provider. Whether the overall workflow is local-only depends on the whole client and model setup, not just this package.

Finally, Sentinel-IR's risk levels are based on recognized AST patterns. A program can conceal behavior through dynamic construction or other patterns the analyzer does not recognize.

For these reasons, Sentinel-IR-MCP is a structural analysis tool, not a complete security scanner and not a proof that code is safe.

1. Testing the integration layer

A setup tool that only works on the author's machine is not much of a setup tool.

The v0.2.2 repository tests cover more than the happy path. According to the test code and release documentation, coverage includes:

• CLI help, version handling and invalid arguments.
• The exposed tool list and annotations.
• MCP communication over standard input/output.
• Analysis tool calls and input validation.
• Rejection of paths outside the allowed folder, including symlink escape cases.
• Unsupported file types and file-size limits.
• Configuration creation and updates while preserving unrelated entries.
• Backups, repeated setup, dry runs and invalid configuration files.
• Refusal of a home folder or disk root as the project scope.
• Client-specific configuration paths and command generation.
• Doctor behavior for successful and failing connections.

Some operating-system-specific configuration paths are tested through simulated environment variables, rather than by launching the full desktop application on each operating system. Similarly, generating and decoding an install link is not the same as verifying a complete real-app click-through flow.

Those distinctions are part of reporting test evidence honestly.

Reproduce the repository tests

If you have Git and Node.js 20 or newer:

git clone https://gitlab.com/jakubrojicek11/sentinel-ir-mcp.git
cd sentinel-ir-mcp
git checkout v0.2.2
npm ci
npm test

This checks out the release tag rather than whatever happens to be on the default branch today.

You can also inspect the source directly:

• "v0.2.2 source tree" (https://gitlab.com/jakubrojicek11/sentinel-ir-mcp/-/tree/v0.2.2)
• "v0.2.2 package metadata" (https://gitlab.com/jakubrojicek11/sentinel-ir-mcp/-/raw/v0.2.2/package.json)
• "v0.2.2 README" (https://gitlab.com/jakubrojicek11/sentinel-ir-mcp/-/raw/v0.2.2/README.md)
• "v0.2.1 to v0.2.2 comparison" (https://gitlab.com/jakubrojicek11/sentinel-ir-mcp/-/compare/v0.2.1...v0.2.2)

1. Known limitations

It is worth listing the boundaries clearly.

Language support: JavaScript and the documented TypeScript variants are supported. Python and arbitrary other languages are not currently supported.

Static analysis: The analyzer recognizes particular structural and risk patterns. It cannot guarantee that all hidden or dynamically constructed behavior will be found.

Incomplete files: A low risk on an incomplete result is not evidence of safety.

Client verification: Doctor performs a real MCP handshake against its own server process, but it does not execute the exact command stored in the client configuration. A real client-side tool call remains useful.

Installation: "npx" may require internet access to download the package. The server's runtime behavior and initial package installation are separate concerns.

Dependencies: The package has runtime dependencies on the official MCP SDK, Zod and Sentinel-IR. It is not a dependency-free package.

Token savings: The measured reduction applies to the specific sample and tokenizer documented above. It is not a universal percentage for all code.

These limitations do not make the tool useless. They define what a responsible integration should and should not claim.

What 0.2.2 changes in practice

Before this release, a developer could integrate Sentinel-IR-MCP by configuring a client manually.

After this release, the repository provides a guided path:

SETUP
|
v
Preview the planned configuration
|
v
Approve the change
|
v
Restart or refresh the client
|
v
DOCTOR
|
v
Verify package plumbing and MCP tools
|
v
GUIDE
|
v
Use a directory-first analysis workflow

There is still work to do to verify the actual AI client's behavior. The process is not a universal one-click installer for every environment.

But it makes common setup tasks easier to repeat, adds a diagnostic route, and documents the intended way for agents to use the tools.

That is the point of the release.

Try it

GitLab tag: "sentinel-ir-mcp v0.2.2" (https://gitlab.com/jakubrojicek11/sentinel-ir-mcp/-/tree/v0.2.2?ref_type=tags)

npm package: "[email protected]" (https://www.npmjs.com/package/sentinel-ir-mcp/v/0.2.2)

Quick start:

npx -y [email protected] setup

Choose your client, review the proposed change, then verify the connection after restarting the client:

npx -y [email protected] doctor --client cursor

Replace "cursor" with the client you actually use. Read the README for client-specific behavior and the limits of the doctor checks.

One final thought

A tool can be technically capable and still be unnecessarily difficult to adopt.

The parser, structural facts and MCP interface matter. So do configuration, diagnostics, instructions and the boundaries around filesystem access.

v0.2.2 focuses on that second layer.

The aim is not to make an AI agent read everything. It is to help it find what matters, understand what it actually inspected, and avoid pretending that missing information is a clean result.

If you try the release, feedback is especially useful on three things:

1. Did setup make your client easier to connect?
2. Did doctor identify a real problem when something was misconfigured?
3. Did the directory-first workflow help your agent focus on the files that mattered?

Those are better signals than simply asking whether the installation command ran.