Connect Tool

Connect a tool: research it, pick the safe route, prove it works

The user said "connect my Holded", "can the agent read our Sage?", "hook up WhatsApp". This skill turns that sentence into a working, documented connection in 01-TOOLS/<TOOL>/, for any tool: the ones with a modern API, and the program installed on an office PC fifteen years ago.

rsc ships no ready-made connections. Every project builds only the ones its user asks for, so the method matters more than any list of vendors: find the truth, take the least dangerous route, prove it, leave it written down.

Before anything: what does the user want to do?

Ask only what the docs cannot answer, in plain words (technical_level in 02-DOCS/wiki/harness/user-profile.md sets the register):

• Which product, exactly? Name, edition, version. "Sage" is five different products.
• Where does it run? In the cloud (a website they log into) or installed on a computer or server in the office.
• Read or write? Reports and questions need reading. Entering invoices needs writing, and writing is a separate, explicit decision (below).

1. Research: the docs decide, never memory

Look it up every time, even for a tool you "know": plans, endpoints and MCP servers change monthly. In this order, stopping when the route is clear:

1. The vendor's own developer docs: search <product> API, <product> developers, <product> MCP. Prefer the vendor domain over blog posts.
2. The official MCP registry (registry.modelcontextprotocol.io) and the vendor's docs for an official MCP server. An official, read-only MCP is often the fastest safe route.
3. Library docs through Context7 when the route is an SDK.
4. Export and import features in the product's user manual: scheduled CSV/Excel exports, FTP drops, official import file formats.
5. Where the data lives for installed software: the vendor's installation guide, the database engine it installs (often SQL Server Express, sometimes Access, Firebird or MySQL).

Write every source into the tool's README.md with its URL and the date you read it. If you find nothing reliable, say so and stop at a question for the vendor; an invented endpoint costs the user a week.

2. Choose the route: the least dangerous one that does the job

Connect, or migrate? If every route above is poor and the program is near end-of-life, or new legal requirements (Spanish e-invoicing, Veri*factu) will force a change anyway, say so plainly and hand the decision to automation-strategy. Check the current dates at the tax authority's site: they have moved before.

3. Least privilege, always

• Read first. Every connection starts read-only, even when the goal is writing.
• Writing is explicit. Only when the user asks for it, only through the vendor's API or its official import format, and only for the objects named.
• Never write directly into a desktop program's database. It bypasses the program's own rules, voids support contracts, and can corrupt accounting. Generate the program's official import file instead, and a person imports it.
• Secrets stay in .env (gitignored, chmod 600). Never in the repo, never in 02-DOCS.

4. Build it in 01-TOOLS/<TOOL>/

Copy 01-TOOLS/_TEMPLATE/ to 01-TOOLS/<TOOL>/ (uppercase id, e.g. HOLDED, SAGE_50) and fill every file: .env.example with the real variable names, CREDENTIALS.md with where each one is generated and how to rotate it, README.md with the route, the sources and their dates, and the permissions granted. Add a row to 01-TOOLS/README.md.

test_connection is the proof, not a formality. It makes one cheap read and prints OK — …. When the connection is meant to be read-only, it must also prove that writing fails, because a read-only promise nobody tested is not one:

bashCopy code
# PostgreSQL: a write must fail with a PERMISSION error. Any other error (wrong host, bad password)
# proves nothing, so it fails the test too instead of passing as "refused".
out=$(psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -c "BEGIN; CREATE TABLE rsc_write_probe(i int); ROLLBACK;" 2>&1) \
  && { echo "FAIL — this user can write" >&2; exit 1; }
grep -qiE "permission denied|read-only transaction" <<<"$out" \
  && echo "OK — writes refused" || { echo "FAIL — unexpected error: $out" >&2; exit 1; }

bashCopy code
# SQL Server: insert into one of the views you exposed; only error 229 (permission denied) passes.
out=$(sqlcmd -S "$MSSQL_HOST" -U "$MSSQL_USER" -P "$MSSQL_PASSWORD" -d "$MSSQL_DB" -b \
  -Q "BEGIN TRAN; INSERT INTO rsc_views.customers DEFAULT VALUES; ROLLBACK;" 2>&1) \
  && { echo "FAIL — this user can write" >&2; exit 1; }
grep -q "Msg 229" <<<"$out" && echo "OK — writes refused" || { echo "FAIL — unexpected error: $out" >&2; exit 1; }

For an API, prove it through the token itself: list its scopes from the vendor's token endpoint or dashboard and fail when a write scope is present. Never fire a real write to "see what happens".

Desktop programs and old ERPs

Most small-business software was never meant to be connected. The safe pattern:

1. Find the data. The vendor's install guide, the Windows ODBC data sources, or the SQL Server instance the program installed (often .\SQLEXPRESS). Access files are .mdb/.accdb.

2. Work on a copy, never the live database. A nightly copy, off business hours. SQL Server Express has no Agent: schedule sqlcmd with a BACKUP DATABASE from the Windows Task Scheduler and restore it where the agent reads. Access: copy the file, then convert or read it with mdbtools (mdb-tables, mdb-export).

3. A dedicated reader. A login that can only SELECT, ideally only on a schema of views that expose what is needed:

   sqlCopy code
   CREATE LOGIN ia_reader WITH PASSWORD = '<from .env>';
   CREATE USER ia_reader FOR LOGIN ia_reader;
   GRANT SELECT ON SCHEMA::rsc_views TO ia_reader;
   ALTER ROLE db_denydatawriter ADD MEMBER ia_reader;
   

4. Reach it privately. Same network, or a private mesh (the TAILSCALE tool). Never open the database port to the internet.

5. Check the support terms. Many vendors restrict direct database access. If they do, use their export or their API instead.

5. Guide the user, in their words

Say what you found, which route you chose and why, and what happens next, in short sentences.

6. Leave it written down

Record the connection in 02-DOCS following the harness wiki protocol: what is connected, the route, the permissions, who owns the credentials, and the date. The next session, or a colleague, reads it instead of starting over.

Anti-patterns

See also

• ../harness/SKILL.md: owns 01-TOOLS/ and 02-DOCS/ as a whole.
• ../api-connector-builder/SKILL.md: auth, pagination and retries once an API is the route.
• ../automation-strategy/SKILL.md: whether to connect, migrate or automate at all.
• ../automation-flows/SKILL.md: chaining the connected tool into a workflow.

Orientación (siempre)

Habla con la voz de orient: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según technical_level en 02-DOCS/wiki/harness/user-profile.md. Cierra cada turno con el bloque-brújula (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). Nunca termines en seco. Protocolo completo: skill orient → skills/orient/references/orientation-contract.md. (Defiere a suggest el "¿instalo la skill que falta?".)