Skip to content

Add basic config and files#1

Merged
bokelley merged 12 commits intomainfrom
bokelley/scope3-client
Oct 20, 2025
Merged

Add basic config and files#1
bokelley merged 12 commits intomainfrom
bokelley/scope3-client

Conversation

@bokelley
Copy link
Copy Markdown
Collaborator

@bokelley bokelley commented Oct 19, 2025

Background

This PR adds the initial project setup files, including configuration, linting, and formatting tools, to establish a baseline for the Scope3 Agentic Client.

Changes

  • Added .env.example for API key and webhook configuration.
  • Added .eslintrc.json for ESLint configuration.
  • Added .prettierrc.json for Prettier configuration.
  • Updated README.md with project overview, installation, quick start, configuration, API resources, webhook server details, development instructions, and examples.
  • Added example TypeScript files (examples/basic-usage.ts, examples/create-campaign.ts, examples/webhook-server.ts) to demonstrate client usage.
  • Added jest.config.js for Jest test configuration.
  • Added openapi.yaml containing the Scope3 Agentic API specification.
  • Added package-lock.json and package.json for dependency management and project configuration.
  • Added src/__tests__/client.test.ts and src/__tests__/webhook-server.test.ts for basic unit tests.
  • Added src/client.ts for the base Scope3 client with MCP SDK integration.
  • Added src/index.ts as the main entry point for the library.
  • Added resource files for all 11 API resource categories (Assets, Brand Agents, Brand Standards, Brand Stories, Campaigns, Channels, Creatives, Sales Agents, Tactics, Media Buys, Notifications, Products).
  • Added src/sdk.ts to expose the main Scope3AgenticClient class.
  • Added src/types/api.ts to define TypeScript types generated from the OpenAPI schema.
  • Added src/types/index.ts for core client and tool response types.
  • Added src/webhook-server.ts for the optional webhook server functionality.
  • Added tsconfig.json for TypeScript compilation configuration.

Testing

  • All generated files are present.
  • Basic tests in src/__tests__ pass.
  • Project builds successfully with npm run build.
  • ESLint and Prettier configurations are applied.

bokelley and others added 12 commits October 18, 2025 04:20
@bokelley @claude
Build TypeScript client for Scope3 Agentic API
733b82b 
- Generate TypeScript types from OpenAPI schema
- Implement core client with bearer token auth
- Create resource wrappers for all API endpoints (assets, brand agents, campaigns, creatives, tactics, media buys, sales agents, notifications, products)
- Add optional webhook server for AdCP events
- Include comprehensive tests and examples
- Full TypeScript support with clean, intuitive API

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@bokelley @claude
Clarify HTTP/REST architecture in README
9d1a2f5 
The Scope3 API exposes MCP tools via HTTP POST endpoints. This client
uses axios (standard HTTP client) to communicate with these endpoints,
which is the correct approach for their HTTP-based MCP server
implementation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@bokelley @claude
Use official MCP SDK for Scope3 API integration
02c04d1 
Replace axios with @modelcontextprotocol/sdk to properly connect to
the Scope3 MCP server at api.agentic.scope3.com/mcp.

Changes:
- Use SSEClientTransport with bearer token authentication
- Convert all API calls to MCP tool invocations
- Update tool names: /endpoint-name -> endpoint_name (underscores)
- Parse JSON responses from MCP tool content
- Update documentation to reflect MCP architecture

All tests passing. The client now uses the official MCP TypeScript SDK
as intended, avoiding any protocol implementation issues.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@bokelley @claude
Switch to HTTP streaming transport for MCP
70f40c3 
Replace SSEClientTransport with StreamableHTTPClientTransport to use
the official MCP Streamable HTTP specification.

Benefits:
- HTTP POST for sending messages (better reliability)
- HTTP GET with SSE for receiving messages
- Automatic reconnection with exponential backoff
- Session management support
- Resumption tokens for interrupted requests

All tests passing. The client now uses the recommended HTTP streaming
transport for production MCP server connections.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@bokelley @claude
Handle both JSON and text responses from MCP tools
2d7f6da 
The Scope3 API returns human-readable text responses for agentic
interaction. Updated the client to gracefully handle both JSON and
plain text responses from MCP tool calls.

Changes:
- Try JSON.parse first for structured data
- Fall back to text response wrapped in { message } object
- Tested successfully with live Scope3 API

Verified with real API key:
✅ brand_agent_list: Returns 113 brand agents
✅ channel_list: Returns 12 channels
✅ campaign_list: Returns 6 campaigns

All tests passing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@bokelley @claude
Rename Scope3SDK to Scope3AgenticClient for clarity
bdecc88 
More descriptive name that clearly indicates this is for the
Scope3 Agentic API. Kept Scope3SDK as legacy export for backwards
compatibility.

Changes:
- Renamed main class: Scope3SDK -> Scope3AgenticClient
- Updated all examples to use new name
- Updated tests and documentation
- Added legacy export for backwards compatibility

All tests passing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@bokelley @claude
Add comprehensive type safety with automated validation
fe6883e 
Implement complete type safety infrastructure with no `any` types:

- **Schema synchronization**: Added `update-schemas` script that downloads
  latest OpenAPI spec from upstream and regenerates TypeScript types
- **Strict typing**: Eliminated all `any` types throughout codebase:
  - Changed ToolResponse<T = any> to ToolResponse<T = unknown>
  - Changed ErrorResponse.details to Record<string, unknown>
  - Made WebhookEvent generic: WebhookEvent<T = Record<string, unknown>>
  - Created SalesAgentAuthConfig interface to replace Record<string, any>
- **Pre-commit validation**: Set up Husky with lint-staged to run on every commit:
  - Formatting (prettier)
  - Linting with auto-fix (eslint)
  - Type checking on full project (tsc --noEmit)
  - Test execution
- **CI pipeline**: Added GitHub Actions workflow with parallel jobs:
  - Type checking
  - Linting
  - Format checking
  - Test execution
  - Build verification
- **Documentation**: Updated README with type safety section explaining approach

All type checks, tests, and builds passing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@bokelley @claude
Fix code review issues: enforce strict type checking
dcca059 
Address critical issues from code review:

- Remove unused WebhookEvent import from test file (was breaking lint)
- Change ESLint no-explicit-any rule from "warn" to "error" to enforce
  the no-any policy in CI
- Optimize pre-commit hook to only run type-check and tests when
  TypeScript files are staged (improves performance for non-TS changes)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@bokelley @claude
Add conductor.json for workspace configuration
66a5ba5 
Configure Conductor to run npm install on workspace startup to ensure:
- Dependencies are installed
- Husky git hooks are set up via prepare script
- Development environment is ready

Also include helpful script shortcuts for common development tasks.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@bokelley @claude
Set up Changesets for versioning and automated NPM publishing
f3093cd 
Implement complete versioning and release automation:

- **Changesets configuration**:
  - Public NPM access for @scope3/agentic-client
  - GitHub changelog integration
  - Scripts: changeset, version, release

- **CI checks**:
  - Require changeset on all PRs to main
  - Clear error message with instructions if missing

- **Automated publishing**:
  - Release workflow on main branch
  - Creates "Version Packages" PR when changesets are merged
  - Auto-publishes to NPM when version PR is merged
  - Requires NPM_TOKEN secret in GitHub

- **Documentation**: Added Contributing section with:
  - How to create changesets
  - Release process workflow
  - CI requirements and bypass instructions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@bokelley @claude
Add changeset for initial release
a5687fa 
Prepare for v0.1.0 release with full feature set.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@bokelley @claude
Update schemas from upstream API
cbb19ec 
Sync with latest OpenAPI spec from https://docs.agentic.scope3.com/openapi.yaml

Major changes:
- Explicit MCP protocol endpoints documented (mcp-initialize, etc.)
- Enhanced tool descriptions and parameter documentation
- Server URLs now include /mcp path
- Auto-generated from TypeScript schemas

The MCP SDK already handles protocol initialization automatically,
so no client code changes required.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@bokelley bokelley merged commit 5feeb69 into main Oct 20, 2025
6 checks passed
@nastassiafulconis nastassiafulconis mentioned this pull request Nov 4, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@bokelley