@civic/x402-mcp 0.0.1

package/.claude/settings.local.json

@@ -0,0 +1,26 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:api.github.com)",
+      "WebFetch(domain:docs.cdp.coinbase.com)",
+      "Bash(pnpm build:*)",
+      "WebFetch(domain:www.npmjs.com)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:x402.org)",
+      "Bash(find:*)",
+      "Bash(grep:*)",
+      "Bash(ls:*)",
+      "Bash(mkdir:*)",
+      "Bash(mv:*)",
+      "Bash(pnpm add:*)",
+      "Bash(pnpm test:*)",
+      "WebFetch(domain:x402.gitbook.io)",
+      "Bash(gh run list:*)",
+      "Bash(gh run view:*)",
+      "Bash(pnpm lint:fix:*)",
+      "Bash(pnpm lint:*)"
+    ],
+    "deny": []
+  }
+}

package/.env.example

@@ -0,0 +1,10 @@
+# For mainnet, use:
+# PAYMENT_NETWORK=base
+# FACILITATOR_URL=<mainnet facilitator url> See here: https://docs.cdp.coinbase.com/x402/network-support
+PAYMENT_NETWORK=base-sepolia
+FACILITATOR_URL=https://x402.org/facilitator
+SENDER_PRIVATE_KEY=0xb81462e5590e4b708a1febadb33bedfed75d94883a7a42d4836dd8e2d46f7f65
+SENDER_WALLET_ADDRESS=0xYourWalletAddressHere
+MCP_SERVER_URL=http://localhost:3022/mcp
+
+RECEIVER_WALLET_ADDRESS=0xYourWalletAddressHere

package/.github/workflows/ci.yml

@@ -0,0 +1,144 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: 'pnpm'
+      
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      
+      - name: Run Biome lint
+        run: pnpm lint
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20.x, 22.x, 24.x]
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+      
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+      
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      
+      - name: Run build
+        run: pnpm build
+      
+      - name: Run tests with coverage
+        run: pnpm test:coverage
+      
+      - name: Upload coverage to Codecov
+        if: matrix.node-version == '20.x'
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          directory: ./coverage
+          fail_ci_if_error: false
+          verbose: true
+
+  type-check:
+    name: Type Check
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: 'pnpm'
+      
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      
+      - name: Run TypeScript compiler
+        run: pnpm tsc --noEmit
+
+  examples:
+    name: Build Examples
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: 'pnpm'
+      
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      
+      - name: Build library
+        run: pnpm build
+      
+      - name: Test example scripts
+        run: |
+          pnpm tsx --version
+          node --version
+
+  security-audit:
+    name: Security Audit
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: 'pnpm'
+      
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      
+      - name: Run security audit
+        run: pnpm audit --audit-level moderate
+        continue-on-error: true

package/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+      
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      
+      - name: Run build
+        run: pnpm build
+      
+      - name: Run tests
+        run: pnpm test run
+      
+      - name: Publish to npm
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
+      
+      - name: Create GitHub Release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: Release ${{ github.ref }}
+          body: |
+            Changes in this release:
+            - See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details
+          draft: false
+          prerelease: false

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/x402-mcp-example.iml" filepath="$PROJECT_DIR$/.idea/x402-mcp-example.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

package/.idea/x402-mcp-example.iml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.tmp" />
+      <excludeFolder url="file://$MODULE_DIR$/temp" />
+      <excludeFolder url="file://$MODULE_DIR$/tmp" />
+      <excludeFolder url="file://$MODULE_DIR$/coverage" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/CLAUDE.md

@@ -0,0 +1,31 @@
+# Civic MCP Development Guidelines
+
+## Overview
+- The project requires heavy understanding of the Model Context Protocol (MCP), which is defined here: https://modelcontextprotocol.io/specification/2025-06-18 , and x402, which is defined here: https://x402.gitbook.io/x402
+
+## Style Guidelines
+- All code should be typescript.
+- Use pnpm as the package manager.
+- Do not use dynamic imports unless there's a very good reason to do so.
+- Except in tests, no stub or placeholder code unless explicitly requested or stated in the spec.
+- Keep functions small where appropriate.
+
+### Testing Strategy
+
+- **Unit Tests**: Test individual functions and services in isolation
+- **Integration Tests**: Test the interaction between multiple services
+- Place tests alongside source files when testing specific functions
+- Use mocks/stubs for external services
+- Use vitest for unit testing.
+- Use playwright for browser-based e2e testing where appropriate
+- Avoid use of 'any'
+- Use stubGlobal and stubEnv if needed, do not change the global or env vars directly
+- Use vi.mocked(...) to provide typesafety when creating expectations
+- Use the Martin Fowler definitions of stubs, mocks, fakes, dummies etc rather than always calling things mocks.
+- Target 90% unit test coverage
+
+# Overall guidelines
+- Whenever making any large changes, first propose a plan, and wait for confirmation before implementing it.
+- No "in a real implementation", you are building the real implementation.
+- No need to maintain legacy solutions, unless explicitly stated, clean up old solutions as you go, to keep the code clean and well-structured.
+- So unless told otherwise, no "backwards-compatibility"

package/DEVELOPER.md

@@ -0,0 +1,181 @@
+# Developer Guide
+
+## Development Setup
+
+### Prerequisites
+- Node.js 20.x or higher
+- pnpm 9.15.4 (automatically installed via corepack if needed)
+
+### Installation
+```bash
+# Clone the repository
+git clone https://github.com/civicteam/x402-mcp.git
+cd x402-mcp
+
+# Install dependencies
+pnpm install
+
+# Build the project
+pnpm build
+
+# Run tests
+pnpm test
+```
+
+## Development Workflow
+
+### Available Scripts
+- `pnpm dev` - Start the development server with hot reload
+- `pnpm build` - Build the TypeScript project
+- `pnpm test` - Run tests in watch mode
+- `pnpm test:coverage` - Run tests with coverage report
+- `pnpm start` - Start the example server
+- `pnpm example:run` - Run the example client
+- `pnpm generate-wallet` - Generate a new wallet for testing
+
+### Testing
+The project uses Vitest for unit testing. Tests should be placed alongside source files or in a `__tests__` directory.
+
+```bash
+# Run tests in watch mode
+pnpm test
+
+# Run tests once with coverage
+pnpm test:coverage
+```
+
+## Release Process
+
+### Prerequisites for Releasing
+1. Ensure you have npm publish access to the `@civic` org
+2. Set up GitHub repository secrets:
+   - `NPM_PUBLISH_TOKEN` - npm automation token for publishing
+   - `CODECOV_TOKEN` (optional) - for coverage reporting
+
+### Release Steps
+
+#### 1. Prepare the Release
+```bash
+# Ensure you're on the main branch with latest changes
+git checkout main
+git pull origin main
+
+# Run tests and build to verify everything works
+pnpm test:coverage
+pnpm build
+
+# Update the version in package.json
+npm version patch  # or minor/major
+# This creates a commit and tag automatically
+```
+
+#### 2. Push the Release
+```bash
+# Push the commit and tag to trigger the release workflow
+git push origin main
+git push origin --tags
+```
+
+#### 3. Automated Release Process
+Once you push the tag, GitHub Actions will automatically:
+1. Run the full test suite across Node.js 20.x, 22.x, and 24.x
+2. Perform type checking
+3. Run security audits
+4. Build the project
+5. Publish to npm with provenance attestation
+6. Create a GitHub release
+
+#### 4. Verify the Release
+- Check the [GitHub Actions](https://github.com/civicteam/x402-mcp/actions) page for build status
+- Verify the package on [npm](https://www.npmjs.com/package/@civic/x402-mcp)
+- Check the [GitHub Releases](https://github.com/civicteam/x402-mcp/releases) page
+
+### Version Guidelines
+- **Patch** (x.x.1): Bug fixes, documentation updates
+- **Minor** (x.1.x): New features, backward-compatible changes
+- **Major** (1.x.x): Breaking changes, major refactors
+
+### Pre-release Versions
+For testing releases before making them public:
+
+```bash
+# Create a pre-release version
+npm version prerelease --preid=beta
+# Results in: 1.0.1-beta.0
+
+# Publish with beta tag
+npm publish --tag beta
+```
+
+### Manual Publishing (Emergency Only)
+If the automated release fails, you can publish manually:
+
+```bash
+# Ensure you're authenticated to npm
+npm login
+
+# Build the project
+pnpm build
+
+# Publish to npm
+npm publish --access public
+```
+
+## CI/CD Pipeline
+
+### Continuous Integration
+The CI workflow runs on every push to `main` and on pull requests:
+- **Test Matrix**: Tests against Node.js 20.x, 22.x, and 24.x
+- **Type Checking**: Validates TypeScript types
+- **Security Audit**: Checks for known vulnerabilities
+- **Coverage**: Reports test coverage to Codecov
+
+### Release Automation
+The release workflow triggers on version tags (`v*`):
+- Builds and tests the project
+- Publishes to npm with provenance
+- Creates a GitHub release
+
+## Troubleshooting
+
+### Common Issues
+
+#### Build Failures
+```bash
+# Clean build artifacts
+rm -rf dist/
+pnpm build
+```
+
+#### Test Failures
+```bash
+# Run tests with verbose output
+pnpm test -- --reporter=verbose
+```
+
+#### Publishing Issues
+- Ensure you're logged into npm: `npm whoami`
+- Check npm access: `npm access ls-packages @civic`
+- Verify the package name isn't taken: `npm view @civic/x402-mcp`
+
+## Contributing
+
+### Pull Request Process
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes and add tests
+4. Ensure all tests pass: `pnpm test:coverage`
+5. Commit with descriptive messages
+6. Push to your fork and create a PR
+
+### Code Style
+- TypeScript with strict typing
+- No use of `any` type
+- Functional programming preferred
+- Small, focused functions
+- JSDoc comments for public APIs
+
+### Commit Guidelines
+- Clear, descriptive commit messages
+- Present tense ("Add feature" not "Added feature")
+- Reference issues when applicable