tiktok-mcp-cli
AGENTS.md1 starsChanged 39 days agoMITView on GitHub
For agents editing this repo. Installation belongs in the README. Tests use a faked fetch and never touch the network or a real token. Keep it that way: a test needing credentials is a test nobody runs. The check that actually counts is a real handshake against the built output, because a green suite says the code compiles, not that the server speaks MCP: Do not re-derive these. Read-only mode removes tools, it does not refuse them, and so does…
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,774 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
The file
We split this AGENTS.md into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
Do not re-derive these.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Working on tiktok-mcp-cli
For agents editing this repo. Installation belongs in the README.
Run it
npm install
npm run build && npm test && npm run typecheckTests use a faked fetch and never touch the network or a real token. Keep it
that way: a test needing credentials is a test nobody runs.
The check that actually counts is a real handshake against the built output, because a green suite says the code compiles, not that the server speaks MCP:
node dist/index.js # then drive it with an MCP clientDecisions already made
Do not re-derive these.
| Decision | Settled as |
| Language | TypeScript, Node >= 22, ESM |
| Package | @thenavidm/tiktok-mcp-cli on npm |
| Framework | Slipway: one definition of each tool serves MCP over stdio and --http, and the CLI |
| Writes | on by default, approval on the irreversible three only |
Things not to break
Read-only mode removes tools, it does not refuse them, and so does
TIKTOK_ALLOW_DESTRUCTIVE=0 for the irreversible three. Slipway leaves them out
of both surfaces (defaults: { destructiveOff: "hide" } in src/app.ts). A
model cannot call a tool it cannot see, and cannot argue with a refusal it never
receives. Making this a runtime error would undo the whole point.
Do not make the drafts tools need approval. They land in the creator's own
inbox and publish nothing. Approving everything trains the reflex that makes
the approval on post_video worthless.
The desktop PKCE challenge is hex, not base64url. src/auth.ts uses
sha256(verifier).digest("hex"). TikTok's web flow and RFC 7636 both use
base64url, so copying a working web implementation here produces an authorize
call TikTok rejects with a generic parameter error.
create_time is seconds, the list cursor is milliseconds. Same endpoint,
two units. format/videos.ts is the only place that converts either.
Error mapping is the product. api/errors.ts turns TikTok's codes into a
sentence naming the fix, and tools/kit.ts maps each code to its exit code. A
new code should get an entry in both rather than being passed through raw.
Where things are
| Path | What is in it |
src/api/ | HTTP client, token refresh, error mapping |
src/app.ts | The Slipway app: tools, settings, login, doctor. Slipway owns MCP, the CLI, --http, the guard, approvals, annotations and the audit log |
src/tools/ | One module per group, plus kit.ts which adapts them to Slipway and maps TikTok's codes to exit codes |
src/format/ | Shaping payloads for a model, and frame.ts, which fences text other people wrote |
src/auth.ts | The loopback OAuth flow, behind login and auth in src/login.ts |
src/doctor.ts | The app key and every account's token and scopes |
INSTALL.md | Long-form auth walkthrough |
Adding a tool
Define it with defineTool, add it to its module's exported array, and pick a
risk. read and write need nothing else; a destructive tool should
provide a summary for the audit log and the approval, and Slipway adds
confirm itself.
Then update the tool count in package.json, the README and the contents
table, because three places carry it and they drift. Every count in a doc is
read off the running binary, never typed: tiktok-cli tools prints it, and
TIKTOK_READ_ONLY=1 tiktok-cli tools prints the read-only one.
Building the desktop extension
npm run build:mcpb # -> desktop-extension/tiktok-<version>.mcpbIt syncs the manifest version from package.json, vendors node_modules into
the bundle, and validates the manifest. Unzip the result and run
node server/index.js against a real MCP client before shipping it: the point
of a .mcpb is that it works on a double click with nothing else installed.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.