Skip to content

Alto 5540 - #10

Merged
dsgou merged 19 commits into
mainfrom
ALTO-5540
Sep 22, 2026
Merged

dsgou merged 19 commits into
mainfrom
ALTO-5540

Conversation

@dsgou

@dsgou dsgou commented Sep 21, 2026

Copy link
Copy Markdown
Contributor

What and why

Adds an optional MCP server, so AI assistants (Claude Code, Claude Desktop, Cursor) can use the Behavioral Signals API directly. Also adds files that help coding agents work in this repo.

  • New behavioralsignals-mcp command. Install with pip install "behavioralsignals[mcp]", or run with uvx --from "behavioralsignals[mcp]" behavioralsignals-mcp. It reads BEHAVIORALSIGNALS_CID and BEHAVIORALSIGNALS_API_KEY.
  • 4 tools:
    • analyze_behavior: uploads audio (a local file or an S3 presigned URL) for behavioral analysis.
    • detect_deepfake: uploads audio or video for deepfake detection.
    • get_result: returns a process's results in pages, optionally only for some tasks.
    • list_processes: lists processes, newest first, with the reason when one failed.
  • The upload tools wait up to wait_seconds (45 by default). If the job takes longer, they return the pid, and the assistant calls get_result later.
  • Results come back as short tab-separated rows (start, end, task, label, confidence). API errors, failed jobs and missing credentials go back to the model as tool errors.
  • mcp is an optional extra (mcp>=2.2.0,<3). The SDK never imports it, so normal installs are unchanged.
  • AGENTS.md (repo map, commands, rules), and a CLAUDE.md that points to it.
  • New README section, "Use with AI assistants (MCP)", with setup for Claude Code, Claude Desktop and Cursor.
  • Version 0.7.0.

After merging:

  • Publish 0.7.0 to PyPI. Until then, the README's uvx command installs 0.6.0, which has no MCP server.
  • This branch and ALTO-5545 (uv in CI) touch the same files. Whichever merges second must run uv lock, fix a small README badge conflict, and change the setup line in AGENTS.md to uv sync -p 3.10 --extra dev.

Related issue or ticket

ALTO-5540

How it was tested

  • 26 new tests in tests/test_mcp_server.py. They use an in-memory MCP client and a fake SDK client, so there are no API calls and no credentials. Full suite: 94 passed.
  • ruff check and ruff format --check pass.
  • Ran the installed behavioralsignals-mcp over stdio. It lists the 4 tools, and list_processes without credentials returns a clear "Missing cid" error.
  • Not yet tried against the real API.

Checklist

  • Ran ruff check, ruff format and pytest
  • Updated README.md and examples/, if usage changed (README only; SDK usage is unchanged)
  • Bumped version in pyproject.toml, if this needs a release

@dsgou
dsgou requested a review from lefteris12 September 21, 2026 12:36
dimitris_sgou and others added 6 commits September 21, 2026 16:49
The reason can end with a long ffmpeg log. This also applies to the
upload tools, which wait for the result the same way.

Co-Authored-By: Claude Opus 5 <[email protected]>
Clients built on the MCP TypeScript SDK cancel a tool call after 60
seconds by default.

Co-Authored-By: Claude Opus 5 <[email protected]>
The API gives no total, so a full page may be the last one.

Co-Authored-By: Claude Opus 5 <[email protected]>
Video jobs always get a Deepfakes client from _api, which mypy can't
see, so ignore union-attr on the three lines that call video methods.

Co-Authored-By: Claude Opus 5 <[email protected]>
@github-actions

Copy link
Copy Markdown

Coverage report

Click to see where and how coverage changed

FileStatementsMissingCoverageCoverage
(new stmts)
Lines missing
  src/behavioralsignals
  mcp_server.py 21-22, 151, 290
  models.py
Project Total  

This report was generated by python-coverage-comment-action

Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md
… section

- Pass --python ">=3.10" to uvx; it fails when the default Python is older.
  ">=3.10" uses any installed newer Python; "3.10" would download 3.10.
- Add Codex setup with codex mcp add.
- Move the uvx and pip run commands to "Running the MCP server manually"
  at the end; the assistant setups don't need them.

Co-Authored-By: Claude Opus 5 <[email protected]>
@dsgou
dsgou merged commit b0213ff into main Sep 22, 2026
11 checks passed
@dsgou
dsgou deleted the ALTO-5540 branch September 22, 2026 13:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants