diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..bcb638c9d --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,104 @@ +# Copilot Onboarding Instructions for MCP Server Go Project + +## Overview + +This repository contains the MCP Server, implemented in Go. The MCP Server is responsible for managing and processing MCP (Message Control Protocol) requests, providing a backend service for clients to interact with MCP resources. It exposes a RESTful API and handles authentication, authorization, and data persistence. + +- **Language:** Go (Golang) +- **Frameworks/Libraries:** Standard Go libraries, plus any listed in `go.mod` +- **Project Type:** Backend server/service +- **Repo Size:** Medium (typically <100 files, mostly Go source) + +## Build Instructions + +1. **Prerequisites** + - Go version >= 1.19 (check `go.mod` for minimum required version) + - Git + - (Optional) Docker, if you wish to run the server in a container + +2. **Bootstrap** + - Clone the repository: + ``` + git clone + cd + ``` + - Ensure Go modules are enabled: + ``` + export GO111MODULE=on + ``` + - Download dependencies: + ``` + go mod tidy + ``` + +3. **Build** + - Build the server binary: + ``` + go build -o mcp-server ./cmd/server + ``` + - The output binary will be `mcp-server` in the repo root. + +4. **Run** + - Start the server: + ``` + ./mcp-server + ``` + - Configuration may be provided via environment variables or config files (see README or `cmd/server/main.go` for details). + +5. **Lint** + - Run linter (if configured): + ``` + golangci-lint run + ``` + - Ensure `golangci-lint` is installed (`go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest`) + +6. **Test** + - Run unit and integration tests: + ``` + go test ./... + ``` + - For coverage: + ``` + go test -cover ./... + ``` + +## Project Structure + +- `cmd/server/main.go`: Entry point for the MCP server. +- `internal/`: Contains core server logic, handlers, and business logic. +- `pkg/`: Shared packages/utilities. +- `go.mod`, `go.sum`: Go module dependencies. +- `README.md`: Project documentation. +- `.github/workflows/`: CI/CD pipeline definitions. +- `configs/`: Configuration files (if present). +- `test/` or `*_test.go` files: Unit and integration tests. + +## CI/CD and Validation + +- **GitHub Actions**: + - Located in `.github/workflows/` + - Typical workflow steps: + - Checkout code + - Set up Go environment + - Run `go mod tidy` + - Run `go build` + - Run `go test ./...` + - Optionally run linter + - All pushes and pull requests trigger the workflow. + - PRs must pass all checks before merging. + +- **Validation Steps**: + - Always run `go mod tidy` before building or testing. + - Ensure all tests pass locally before pushing changes. + - Lint code before submitting PRs. + - Check for any required environment variables or config files in the README. + +## Additional Notes + +- If you encounter build or test failures, check for missing dependencies or incorrect Go version. +- For Docker usage, see any provided `Dockerfile` in the repo root or `build/` directory. +- For more details, refer to `README.md` and comments in `main.go`. + +--- + +**Trust these instructions for onboarding and development. Only perform additional searches if information here is incomplete or found to be in error.** diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 000000000..6e1eaaf65 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,100 @@ +# For most projects, this workflow file will not need changing; you simply need +# to commit it to your repository. +# +# You may wish to alter this file to override the set of languages analyzed, +# or to provide custom queries or build logic. +# +# ******** NOTE ******** +# We have attempted to detect the languages in your repository. Please check +# the `language` matrix defined below to confirm you have the correct set of +# supported CodeQL languages. +# +name: "CodeQL Advanced" + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + schedule: + - cron: '21 14 * * 2' + +jobs: + analyze: + name: Analyze (${{ matrix.language }}) + # Runner size impacts CodeQL analysis time. To learn more, please see: + # - https://gh.io/recommended-hardware-resources-for-running-codeql + # - https://gh.io/supported-runners-and-hardware-resources + # - https://gh.io/using-larger-runners (GitHub.com only) + # Consider using larger runners or machines with greater resources for possible analysis time improvements. + runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }} + permissions: + # required for all workflows + security-events: write + + # required to fetch internal or private CodeQL packs + packages: read + + # only required for workflows in private repositories + actions: read + contents: read + + strategy: + fail-fast: false + matrix: + include: + - language: actions + build-mode: none + - language: go + build-mode: autobuild + # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift' + # Use `c-cpp` to analyze code written in C, C++ or both + # Use 'java-kotlin' to analyze code written in Java, Kotlin or both + # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both + # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis, + # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning. + # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how + # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + # Add any setup steps before running the `github/codeql-action/init` action. + # This includes steps like installing compilers or runtimes (`actions/setup-node` + # or others). This is typically only required for manual builds. + # - name: Setup runtime (example) + # uses: actions/setup-example@v1 + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: ${{ matrix.language }} + build-mode: ${{ matrix.build-mode }} + # If you wish to specify custom queries, you can do so here or in a config file. + # By default, queries listed here will override any specified in a config file. + # Prefix the list here with "+" to use these queries and those in the config file. + + # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs + # queries: security-extended,security-and-quality + + # If the analyze step fails for one of the languages you are analyzing with + # "We were unable to automatically build your code", modify the matrix above + # to set the build mode to "manual" for that language. Then modify this step + # to build your code. + # â„šī¸ Command-line programs to run using the OS shell. + # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun + - if: matrix.build-mode == 'manual' + shell: bash + run: | + echo 'If you are using a "manual" build mode for one or more of the' \ + 'languages you are analyzing, replace this with the commands to build' \ + 'your code, for example:' + echo ' make bootstrap' + echo ' make release' + exit 1 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 + with: + category: "/language:${{matrix.language}}" diff --git a/.github/workflows/generator-generic-ossf-slsa3-publish.yml b/.github/workflows/generator-generic-ossf-slsa3-publish.yml new file mode 100644 index 000000000..400a8de0c --- /dev/null +++ b/.github/workflows/generator-generic-ossf-slsa3-publish.yml @@ -0,0 +1,68 @@ +# This workflow uses actions that are not certified by GitHub. +# They are provided by a third-party and are governed by +# separate terms of service, privacy policy, and support +# documentation. + +# This workflow lets you generate SLSA provenance file for your project. +# The generation satisfies level 3 for the provenance requirements - see https://slsa.dev/spec/v0.1/requirements +# The project is an initiative of the OpenSSF (openssf.org) and is developed at +# https://github.com/slsa-framework/slsa-github-generator. +# The provenance file can be verified using https://github.com/slsa-framework/slsa-verifier. +# For more information about SLSA and how it improves the supply-chain, visit slsa.dev. + +name: SLSA generic generator +on: + workflow_dispatch: + release: + types: [created] + +jobs: + build: + runs-on: ubuntu-latest + outputs: + digests: ${{ steps.hash.outputs.digests }} + + steps: + - uses: actions/checkout@v5 + + # ======================================================== + # + # Step 1: Build your artifacts. + # + # ======================================================== + - name: Build artifacts + run: | + # Build the project and generate real artifacts. + npm ci + npm run build + # Package the build output as an artifact (example: tarball) + tar -czf dist.tar.gz dist/ + + # ======================================================== + # + # Step 2: Add a step to generate the provenance subjects + # as shown below. Update the sha256 sum arguments + # to include all binaries that you generate + # provenance for. + # + # ======================================================== + - name: Generate subject for provenance + id: hash + run: | + set -euo pipefail + + # List the artifacts the provenance will refer to. + files=$(ls dist.tar.gz) + # Generate the subjects (base64 encoded). + echo "digests=$(sha256sum $files | base64 -w0)" >> "${GITHUB_OUTPUT}" + + provenance: + needs: [build] + permissions: + actions: read # To read the workflow path. + id-token: write # To sign the provenance. + contents: write # To add assets to a release. + uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v1.4.0 + with: + base64-subjects: "${{ needs.build.outputs.digests }}" + upload-assets: true # Optional: Upload to a new release