sp-api: CLI Agentic para SharePoint
supermem613/sp-api
CLI agentic para SharePoint com skill thin para agentes de IA
Ver no GitHubUma CLI agentic para SharePoint que funciona como skill integrada para Claude Code, GitHub Copilot CLI e outros agentes de IA. Oferece autenticação, roteamento de comandos, gerenciamento de listas, documentos e busca com saída estruturada em JSON, sem exposição de HTTP bruto.
Instalação
npx convez-ai supermem613/sp-api1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar operações em SharePoint (listas, itens, arquivos) via agentes IA
- Descobrir e explorar sites SharePoint, listas e bibliotecas programaticamente
- Integrar SharePoint em fluxos de trabalho com Claude Code ou GitHub Copilot CLI
- Buscar documentos e gerenciar versões em SharePoint com semântica agentic
Veredito

Ferramenta sólida para integração agentic com SharePoint, bem estruturada com autenticação encapsulada e output determinístico. Cobre casos reais (CRUD de listas, upload/download de arquivos, busca), mas está em fase inicial e requer conhecimento de SharePoint.
README
A tradução para o português deste README ainda está na fila.
sp-api
An agentic SharePoint CLI with a bundled thin skill for Claude Code, GitHub Copilot CLI, and other coding agents.
What It Does
This repo is first and foremost the sp-api CLI. It includes a bundled skill only as a thin router so agents know when and how to call the CLI. Agents use semantic SharePoint capability commands instead of raw HTTP verbs. The CLI owns auth, command routing, generated help, generated schema, JSON envelopes, and the current lists/files implementation.
sp-api is agentic by default:
- JSON stdout for non-help commands
- Progress and remediation on stderr
sp-api schemaas the machine-readable source of truth- Help generated from the same capability registry as schema
- No raw HTTP passthrough
Questions and Tasks It Can Handle
Auth and Setup
- "Log in to this SharePoint site so future commands can use it"
- "Am I authenticated, and which auth file is being used?"
- "Clear the saved SharePoint browser profile and auth state"
- "Check whether my local
sp-apiinstall is healthy" - "Update this git-clone install of
sp-api"
Site Discovery
- "What site am I connected to? Show the title, URL, description, and template"
- "Show me the visible lists and libraries on this site with item counts and root folder paths"
- "Which lists and document libraries should I inspect before making changes?"
Lists and List Items
- "Show me all visible lists on this site with their item counts"
- "Get metadata for the Tasks list"
- "Show me the field schema for the Projects list, including internal names, types, required flags, read-only flags, and choices"
- "Add a text, datetime, or choice field to a list, idempotently with
--if-missing, so a fixture list can be set up safely on every run" - "Get the first 25 items from the Tasks list with only Title, Id, and Status"
- "Create a new list called Project Tracker"
- "Create a new item in the Issues list with Title 'Server outage' and Priority 'High'"
- "Update item 42 in the Tasks list and set Status to Completed"
- "Delete item 42 from the Tasks list"
- "Delete the old TestData list"
Files and Folders
- "List files in the Shared Documents library"
- "Show folders and files under
/sites/team/Shared Documents" - "Get metadata for
/sites/team/Shared Documents/report.docx" - "Download the contents of
/sites/team/Shared Documents/config.json" - "Download
/sites/team/Shared Documents/logo.pngto a local file with--out" - "Upload a small text file called notes.txt to Shared Documents"
- "Upload the contents of a local file as
SKILL.md" - "Create, recycle, or delete a SharePoint folder by server-relative path"
- "Recycle old.txt without permanently deleting it"
- "Delete old.txt permanently"
- "Move draft.docx to the Archive folder"
- "Copy budget.xlsx to a backup location"
Search
- "Search this SharePoint site for documents containing 'quarterly review'"
- "Find the top 10 results for Project Apollo and return Title and Path"
- "Search with explicit managed properties so an agent can summarize the matches"
Pages
- "List all modern Site Pages with titles and paths"
- "Read the canvas content and metadata for Home.aspx"
- "Check out the Home page before editing it"
- "Update the title or description fields for a Site Pages item"
- "Publish Home.aspx with a publish comment"
- "Discard the checkout for Home.aspx"
Permissions
- "Show me the role assignments for this site"
- "Who has access to this site and what roles do they have?"
- "Inspect web-level permissions before planning a permission change"
Schema, Help, and Agent Routing
- "What SharePoint capabilities does
sp-apiexpose right now?" - "Show the machine-readable schema for
pages publish" - "Show generated help for
search query" - "Tell me whether a capability is implemented or still planned without falling back to raw HTTP"
Current Command Surface
sp-api auth login | logout | status
sp-api lists list | get | fields | create | delete | add-field | items | add-item | update-item | delete-item
sp-api files list | get | download | upload | create-folder | delete-folder | recycle-folder | delete | move | copy | folder | recycle
sp-api search query
sp-api sites get | discovery
sp-api pages list | get | checkout | save-fields | publish | discard-checkout
sp-api permissions get
sp-api schema [capability] [verb]
sp-api doctor
sp-api update
Planned capability groups are exposed in sp-api schema so agents can see what is not implemented yet without falling back to raw HTTP.
Quick Start
git clone https://github.com/supermem613/sp-api
cd sp-api
npm install
npm run build
npm link
sp-api doctor
Authenticate once:
sp-api auth login --site contoso.sharepoint.com/sites/mysite
Then use semantic commands:
sp-api lists list
sp-api lists items --title Tasks --select Title,Id,Status --top 25
sp-api files list --folder "/sites/mysite/Shared Documents"
sp-api files create-folder --path "/sites/mysite/Shared Documents/Test Folder"
sp-api schema lists add-item
Bundled Skill
The skill under .claude/skills/sp-api is not the product surface. It is a generated router plus lazy-loaded references. Install the CLI first, then install or copy the skill so agents route SharePoint tasks to sp-api.
Claude Code
/install supermem613/sp-api
Copilot CLI / Other Agents
Copy .claude/skills/sp-api into the agent's skill directory and install the package dependencies from this repo. The skill routes agents to sp-api.
Auth
sp-api auth login uses Playwright with Microsoft Edge persistent context. First run may open Edge for interactive login. Subsequent runs use the saved browser profile headlessly.
- Browser profile:
~/.sp-api/browser-profile/ - Auth file:
~/.sp-api/auth.json - Force re-login:
sp-api auth login --site <site> --force - Clear auth:
sp-api auth logout
No app registration, client ID, tenant config, or secret is required.
Tests
npm run build
npm test
npm run test:integration
npm run build validates generated artifacts and the sp-api bin before local linking or publishing. npm link and npm run link:local are supported for local development. For linked or git-clone installs, sp-api update pulls with git pull --ff-only, skips install/build when already current, and otherwise runs npm install --no-audit --no-fund plus npm run build.
npm test covers the sp-api registry, schema generation, help generation, JSON envelopes, SharePoint auth/REST internals, no raw fallback, auth isolation, package bin wiring, and SKILL router sync.
npm run test:integration is the live SharePoint test suite and requires an authenticated site.
Docs
docs/AGENTIC_CONTRACT.md—sp-apistdout/stderr, schema, help, and command contractdocs/setup-guide.md— install and authdocs/architecture.md— registry, CLI, and auth architecturedocs/api-coverage.md— current and planned capability coveragedocs/auth-deep-dive.md— Playwright persistent-context auth detailsCONTRIBUTING.md— development workflow