AsItIs

@asitis/mcp

Read-only MCP server for markdown and AI agent steering files. From AsItIs, the markdown editor that never rewrites your file. MIT licensed. Source, issues and the Claude Code plugin: github.com/Katta041/asitis-agent-tools.

It gives your coding agent six tools to read, outline, lint, budget and suggest fixes for CLAUDE.md, AGENTS.md, GEMINI.md, SKILL.md, subagents, commands, rules, Cursor .mdc rules, Copilot instructions and memory files, without being able to change any of them. The same package has an asitis command for CI and pre-commit.

• No writes. There is no write, patch or delete tool, and no write code in the package.
• No network. No telemetry, no update check, no remote calls. It speaks MCP over stdio only.
• Your folder only. It reads only markdown files under the folder (or folders) you start it with, plus its own .asitisrc.json and the root .gitmodules, unless a call asks for the opt-in skill or config scan.

Install

Requires Node 22.13 or later. Always pin the version; never use @latest in an agent config. MCP clients start servers outside your project, so give --root as an absolute path.

Check that it runs:

npx -y @asitis/mcp@0.3.0 --version

Claude Code

Run this in your project folder:

claude mcp add asitis -- npx -y @asitis/mcp@0.3.0 --root "$PWD"

Or install the Claude Code plugin, which adds a byte-clean editing skill, /asitis:md-lint, /asitis:md-budget and an optional guard hook, and runs this server under Node's permission model:

claude plugin marketplace add Katta041/asitis-agent-tools

claude plugin install asitis@asitis

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows:

{

"mcpServers": { "asitis": { "command": "npx", "args": ["-y", "@asitis/mcp@0.3.0", "--root", "/absolute/path/to/project"] } } }

Cursor

.cursor/mcp.json in the project (or ~/.cursor/mcp.json):

{

"mcpServers": { "asitis": { "command": "npx", "args": ["-y", "@asitis/mcp@0.3.0", "--root", "${workspaceFolder}"] } } }

If your Cursor version does not expand ${workspaceFolder}, use an absolute path. The server refuses a root that still contains ${...} rather than guessing.

VS Code

.vscode/mcp.json in the project (Copilot agent mode). VS Code uses the servers key, not mcpServers:

{

"servers": { "asitis": { "type": "stdio", "command": "npx", "args": ["-y", "@asitis/mcp@0.3.0", "--root", "${workspaceFolder}"] } } }

Codex (CLI, IDE and desktop)

~/.codex/config.toml:

[mcp_servers.asitis]

command = "npx" args = ["-y", "@asitis/mcp@0.3.0", "--root", "/absolute/path/to/project"]

Gemini CLI

.gemini/settings.json in the project (or ~/.gemini/settings.json):

{

"mcpServers": { "asitis": { "command": "npx", "args": ["-y", "@asitis/mcp@0.3.0", "--root", "/absolute/path/to/project"] } } }

Hardened: Node's permission model

Run the file directly under Node's permission model so Node itself denies writes and child processes (and network access on Node 25 and later):

npm install -g @asitis/mcp@0.3.0

node --permission \ --allow-fs-read="$(npm root -g)/@asitis/mcp" \ --allow-fs-read=/absolute/path/to/project \ "$(npm root -g)/@asitis/mcp/dist/asitis-mcp.mjs" --root /absolute/path/to/project

In a client config, command is node and every other word goes in args, in the same order. Replace $(npm root -g) with the folder that command prints, because configs do not run shell commands.

If a desktop app cannot find npx or node, use its full path (run which npx, or where npx on Windows) as the command.

CLI and CI

The package also has an asitis command for scripts, CI and pre-commit. It lints the same way as lint_steering and exits 0 (clean), 1 (findings at or above --fail-on, default error), 2 (something you can fix, one line on stderr) or 3 (a bug in asitis).

npx -y -p @asitis/mcp@0.3.0 asitis lint                      # every steering file under the current folder

npx -y -p @asitis/mcp@0.3.0 asitis lint CLAUDE.md AGENTS.md # only these files npx -y -p @asitis/mcp@0.3.0 asitis lint --format sarif > asitis.sarif npx -y -p @asitis/mcp@0.3.0 asitis lint --fix-preview=safe | git apply # apply the safe fixes yourself npx -y -p @asitis/mcp@0.3.0 asitis budget # tokens each agent loads every session

Formats: text, json, sarif (the standard report format GitHub code scanning reads) and github (pull request annotations). With github, only errors and warnings become annotations; add --annotate-notes to annotate notes as well. It never writes a file; --fix-preview prints a diff and you decide whether to apply it. asitis lint --help and asitis budget --help list each command's options.

$ npx -y -p @asitis/mcp@0.3.0 asitis lint --include skills

.claude/skills/release/SKILL.md:4:1 warning sec-skill-allowed-tools allowed-tools pre-approves "Bash" (any shell command), so during the turn that invokes this skill those calls go ahead without asking you; scope each entry to the commands it needs, for example Bash(git status *) or WebFetch(domain:docs.example.com)

CLAUDE.md:7:1 warning duplicate-rule Same rule as line 5: "Run pnpm test before every commit". Duplicates cost context and drift apart when one is edited; keep one CLAUDE.md:9:1 warning broken-link Relative link target not found: "docs/api.md". Fix the path or remove the link CLAUDE.md:11:1 note hidden-comment 1 comment (HTML or [//]: # style) is hidden in rendered views on line 11: "maintainer note: keep this short". It does not read like an instruction to an agent; Claude Code strips it from CLAUDE.md at session start, though its Read tool and other agents still see it, so check that it says what you expect

Linted 2 files: 0 errors, 3 warnings, 1 note. Skill scan: 1 skill folder, 0 scripts and 0 markdown files read, 0 other files checked for executable headers (0 files in all).

That run exits 0: with the default --fail-on error only errors fail the build. Planted invisible or bidirectional characters, and hidden comments that tell the agent to ignore instructions, hide something, run a command or reach for secrets, are errors, so they fail the build by default. Pass --fail-on warning to fail on warnings too.

GitHub Action. Runs the bundled CLI with no npm install and puts findings on the pull request:

permissions:

contents: read jobs: asitis: runs-on: ubuntu-latest steps:

• uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false
• uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: node-version: 22
• uses: Katta041/asitis-agent-tools@v0.3.0

pre-commit. Lints only the staged steering files:

repos:

• repo: https://github.com/Katta041/asitis-agent-tools rev: v0.3.0 hooks:
• id: asitis-lint

docs/ci.md covers the Action's inputs and SARIF upload, lefthook, husky and GitLab CI. Every flag and exit code is in docs/cli-contract.md.

Config

Put an .asitisrc.json at the project root. Everything is optional:

{

"$schema": "https://raw.githubusercontent.com/Katta041/asitis-agent-tools/main/packages/mcp/schema/asitisrc-1.json", "extends": "recommended", "rules": { "duplicate-rule": "off", "length": ["warning", { "claudeMdLines": 300 }] }, "ignore": ["vendor/", "examples/"], "overrides": [{ "files": ["docs/**"], "rules": { "contradiction": "off" } }], "include": ["skills", "config"] }

A typo stops the run with the file, line and a suggestion (.asitisrc.json line 2: unknown key "rulez" (did you mean "rules"?)).

To silence one finding, put a comment above it with the rule id: , or asitis-disable-file for the whole file. The reason after -- is optional; when you give one it is carried into the JSON and SARIF output. The rule id is the word after the severity in each finding, and docs/rules/ lists them all. Security rules (hidden instructions, invisible characters, the sec-* rules) cannot be silenced by a comment, since a comment is exactly what an attacker would add; turn them off in .asitisrc.json or a baseline, where it shows in review. For an existing repo, asitis lint --format json --write-baseline > .asitis-baseline.json and then --baseline .asitis-baseline.json reports only new findings.

Every rule has a page with examples: docs/rules/.

Tools

| find_steering_files | Every steering file, grou