### Frontend Development Setup (TypeScript/Node.js)

Source: https://github.com/kritsanan1/mcpcan/blob/main/CONTRIBUTING.md

Instructions for setting up the TypeScript frontend. This involves installing dependencies using pnpm, copying environment variables, and starting the development server. Requires Node.js 18+ and pnpm.

```bash
cd web
pnpm install
cp .env.example .env.local
# Edit environment variables as needed
pnpm dev
```

--------------------------------

### Backend Development Setup (Go)

Source: https://github.com/kritsanan1/mcpcan/blob/main/CONTRIBUTING.md

Steps to set up the Go backend. This includes downloading dependencies, copying a configuration example, and running the main gateway application. Requires Go 1.21+ and `go mod`.

```bash
cd backend
go mod download
cp config/gateway.yaml.example config/gateway.yaml
# Edit configuration files as needed
go run cmd/gateway/main.go
```

--------------------------------

### Custom Installation using Helm

Source: https://github.com/kritsanan1/mcpcan/blob/main/README.md

This guide outlines the steps for a custom installation of MCPCan using Helm. It involves installing dependencies, configuring values, and then deploying the platform. It supports custom domains and HTTPS configurations.

```bash
# 1. Install dependencies (skip if k3s/Helm is already installed)
./scripts/install-run-environment.sh       # International mirrors
# ./scripts/install-run-environment.sh --cn  # China mirrors

# 2. Copy and modify configuration
cp helm/values.yaml helm/values-custom.yaml
# Edit helm/values-custom.yaml to set global.domain and other parameters

# 3. Install platform
helm install mcpcan ./helm -f helm/values-custom.yaml \
  --namespace mcpcan --create-namespace --timeout 600s --wait

```

--------------------------------

### Fast Installation Script for MCP CAN (Bash)

Source: https://github.com/kritsanan1/mcpcan/blob/main/README.md

This bash script, install-fast.sh, automates the quick installation of the MCP CAN platform on clean Linux servers. It handles the installation of essential components like k3s, ingress-nginx, and Helm, followed by the deployment of the MCP CAN platform itself. This is the recommended method for a streamlined setup.

```bash
# Standard installation (International mirrors)
./scripts/install-fast.sh
```

--------------------------------

### Install Dependencies with npm

Source: https://github.com/kritsanan1/mcpcan/blob/main/frontend/README.md

Installs all the necessary project dependencies using npm. This is a prerequisite for running any other npm scripts.

```shell
npm install
```

--------------------------------

### Go Backend Coding Standard Example

Source: https://github.com/kritsanan1/mcpcan/blob/main/CONTRIBUTING.md

Illustrates good practice for Go backend code, focusing on error handling and clear function signatures. Adheres to Go coding standards.

```go
// Good
func GetUserByID(id string) (*User, error) {
    if id == "" {
        return nil, errors.New("user ID cannot be empty")
    }
    // Implementation...
}
```

--------------------------------

### Accelerated Installation (China Mirrors)

Source: https://github.com/kritsanan1/mcpcan/blob/main/README.md

This script performs a fast installation of MCPCan using China-based mirrors for improved download speeds. It requires execution with the --cn flag.

```bash
./scripts/install-fast.sh --cn

```

--------------------------------

### Full Stack Development with Docker Compose

Source: https://github.com/kritsanan1/mcpcan/blob/main/CONTRIBUTING.md

Launches the full stack development environment using Docker Compose. This command requires Docker and Docker Compose to be installed and configured.

```bash
docker-compose -f docker-compose.dev.yml up
```

--------------------------------

### Vue.js Application Setup: package.json Configuration

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

This package.json file configures a Vue.js application using TypeScript and Vite. It defines project metadata, engine requirements, and scripts for development, building, previewing, type checking, and linting. It also lists essential dependencies.

```json
{
  "name": "qm_mcp_market_admin",
  "version": "v1.5.0",
  "type": "module",
  "engines": {
    "node": "^20.19.0 || >=22.12.0"
  },
  "scripts": {
    "dev": "vite",
    "build": "run-p type-check \"build-only {@}\" --",
    "preview": "vite preview",
    "type-check": "vue-tsc --build",
    "lint": "eslint . --fix"
  },
  "dependencies": {
    "vue": "^3.5.18",
    "vue-router": "^4.5.1",
    "pinia": "^3.0.3",
    "axios": "^1.12.2",
    "element-plus": "^2.11.3",
    "@vueuse/core": "^13.6.0",
    "typescript": "~5.8.0"
  }
}
```

--------------------------------

### MCP Gateway Service Configuration with YAML

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

Example YAML configuration file for the MCP gateway service. Defines HTTP port, database connection details for MySQL and Redis, and logging settings. Assumes services like 'mysql-svc' and 'redis-svc' are available.

```yaml
# backend/config-example/gateway.yaml
server:
  httpPort: 8085

database:
  mysql:
    host: "mysql-svc"
    port: 3306
    database: mcp_dev
    username: mcp_user
    password: dev-password
  redis:
    host: "redis-svc"
    port: 6379
    password: "dev-redis-password"
    db: 0

log:
  level: debug
  format: text
```

--------------------------------

### Run Development Server with npm

Source: https://github.com/kritsanan1/mcpcan/blob/main/frontend/README.md

Starts the development server with hot-reloading enabled, allowing for rapid iteration during development. Uses Vite's development server.

```shell
npm run dev
```

--------------------------------

### Clone MCPCan Repository with Git

Source: https://github.com/kritsanan1/mcpcan/blob/main/CONTRIBUTING.md

This snippet demonstrates how to fork the MCPCan repository, clone it locally, and add the upstream repository for synchronization. It requires Git to be installed.

```bash
git clone https://github.com/your-username/mcpcan.git
cd mcpcan
git remote add upstream https://github.com/kymo-mcp/mcpcan.git
```

--------------------------------

### Integration Testing with Docker Compose

Source: https://github.com/kritsanan1/mcpcan/blob/main/CONTRIBUTING.md

Sets up and runs integration tests using Docker Compose. This command ensures all containers defined in 'docker-compose.test.yml' are started and will abort if any container exits prematurely.

```bash
docker-compose -f docker-compose.test.yml up --abort-on-container-exit
```

--------------------------------

### MCP Authorization Service Configuration with YAML

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

Example YAML configuration file for the MCP authorization service. Includes HTTP port, a secret key, database connection details (MySQL, Redis), logging configuration, and storage paths for code and static files. Assumes specific service availability.

```yaml
# backend/config-example/authz.yaml
server:
  httpPort: 8082

secret: "dev-app-secret"

database:
  mysql:
    host: "mysql-svc"
    port: 3306
    database: mcp_dev
    username: mcp_user
    password: dev-password
  redis:
    host: "redis-svc"
    port: 6379
    password: "dev-redis-password"
    db: 0

log:
  level: debug
  format: text

storage:
  rootPath: ./data
  codePath: ./data/code-package
  staticPath: ./data/static
```

--------------------------------

### TypeScript Frontend Coding Standard Example

Source: https://github.com/kritsanan1/mcpcan/blob/main/CONTRIBUTING.md

Demonstrates good practice for TypeScript frontend code, emphasizing type safety with interfaces and using functional components with hooks. Follows TypeScript ESLint rules.

```typescript
// Good
interface UserProfileProps {
  user: User;
  onUpdate: (user: User) => void;
}

const UserProfile: React.FC<UserProfileProps> = ({ user, onUpdate }) => {
  // Implementation...
};
```

--------------------------------

### Get Instance Status

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

Retrieves the current status of a specific MCP instance.

```APIDOC
## GET /market/instance/status/{instanceId}

### Description
Retrieves the operational status and readiness of a given instance.

### Method
GET

### Endpoint
`/market/instance/status/{instanceId}`

### Parameters
#### Path Parameters
- **instanceId** (string) - Required - The unique identifier of the instance.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET https://demo.mcpcan.com/market/instance/status/inst-12345 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (200)
- **code** (integer) - Status code of the operation.
- **data** (object) - Contains instance status details.
  - **instanceId** (string) - The ID of the instance.
  - **status** (string) - The current operational status (e.g., "running").
  - **isReady** (boolean) - Indicates if the instance is ready to serve requests.
  - **lastCheckTime** (integer) - Timestamp of the last status check.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "instanceId": "inst-12345",
    "status": "running",
    "isReady": true,
    "lastCheckTime": 1735646400
  }
}
```
```

--------------------------------

### Get Instance Status with cURL

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

Retrieves the current status of a specific MCP instance using a cURL command. Requires an authorization token. The response includes instance ID, status, readiness, and last check time.

```shell
curl -X GET https://demo.mcpcan.com/market/instance/status/inst-12345 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Go Service Implementation: Gateway Application Entrypoint

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

This Go code demonstrates the main entrypoint for a gateway application. It initializes and runs the application instance, handling potential errors during these stages. It relies on the 'app' package from the internal gateway module.

```go
// backend/cmd/gateway/main.go
package main

import (
	"log"
	"os"
	"github.com/kymo-mcp/mcpcan/internal/gateway/app"
)

func main() {
	// Create application instance
	appInstance, err := app.New()
	if err != nil {
		log.Fatalf("Failed to create application instance: %v", err)
		os.Exit(1)
	}

	// Initialize application
	if err := appInstance.Initialize(); err != nil {
		log.Fatalf("Failed to initialize application: %v", err)
		os.Exit(1)
	}

	// Run application
	if err := appInstance.Run(); err != nil {
		log.Fatalf("Failed to run application: %v", err)
		os.Exit(1)
	}
}
```

--------------------------------

### Build and Deployment Commands with Makefile

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

A set of Makefile targets for building backend services (Go), frontend (pnpm), Docker images, running tests, linters, and cleaning build artifacts. Supports building all services, specific services, and pushing images to a registry.

```bash
# Build all backend services
make go-build-all

# Build specific services
make go-build-gateway
make go-build-authz
make go-build-market
make go-build-init

# Build frontend
make pnpm-build

# Build everything
make build-all

# Build Docker images
make docker-build-all

# Build and push specific service
make docker-build-push-gateway
make docker-build-push-authz

# Push all images
make docker-push-all IMAGE_REGISTRY=your-registry

# Run tests
make test-all

# Run linters
make lint-all

# Clean build artifacts
make clean
```

--------------------------------

### Go Service Implementation: User Service Pattern

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

This Go code showcases a typical service implementation pattern using the Gin framework. It includes dependency injection for business logic and handles user creation requests, including password management and validation. It depends on packages for API definitions, business logic, and common utilities.

```go
// Example service implementation pattern
package service

import (
	"github.com/gin-gonic/gin"
	"github.com/kymo-mcp/mcpcan/api/authz/user"
	"github.com/kymo-mcp/mcpcan/internal/authz/biz"
	"github.com/kymo-mcp/mcpcan/pkg/common"
)

type UserService struct {
	userBiz *biz.UserBiz
}

func NewUserService() *UserService {
	return &UserService{
		userBiz: biz.NewUserBiz(),
	}
}

func (s *UserService) CreateUser(c *gin.Context) {
	var req user.CreateUserRequest
	if err := common.BindAndValidate(c, &req); err != nil {
		return
	}

	userModel := s.convertCreateRequestToModel(&req)

	if req.Password != "" {
		if err := s.userBiz.SetUserPassword(c.Request.Context(), userModel, req.Password); err != nil {
			common.GinError(c, i18nresp.CodeInternalError, "Failed to set user password")
			return
		}
	}

	if err := s.userBiz.CreateUser(c.Request.Context(), userModel); err != nil {
			common.GinError(c, i18nresp.CodeInternalError, err.Error())
			return
		}

	response := s.convertModelToProto(userModel)
	common.GinSuccess(c, response)
}
```

--------------------------------

### Clone MCP CAN Deployment Repository (Bash)

Source: https://github.com/kritsanan1/mcpcan/blob/main/README.md

This snippet demonstrates how to clone the MCP CAN deployment repository using Git. It provides commands for both GitHub and Gitee, catering to international and China-based users respectively. It's the first step in setting up the MCP CAN platform.

```bash
# GitHub (International)
git clone https://github.com/Kymo-MCP/mcpcan-deploy.git
cd mcpcan-deploy

# Gitee (Recommended for China)
git clone https://gitee.com/kymomcp/mcpcan-deploy.git
cd mcpcan-deploy
```

--------------------------------

### Backend Testing with Go

Source: https://github.com/kritsanan1/mcpcan/blob/main/CONTRIBUTING.md

Runs all Go tests in the backend directory, including race condition detection and coverage reporting. Ensure you are in the 'backend' directory before executing these commands.

```bash
cd backend
go test ./...
go test -race ./...
go test -cover ./...
```

--------------------------------

### MCP Instance Management API - Bash

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

Shows how to interact with the MCP instance management API to list existing instances with pagination and create new MCP service instances. Requires an Authorization header with a JWT token.

```bash
# List MCP instances
curl -X POST https://demo.mcpcan.com/market/instance/list \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ 
    "page": "1",
    "pageSize": "20"
  }'

# Response:
# {
#   "code": 0,
#   "data": {
#     "list": [
#       {
#         "instanceId": "inst-12345",
#         "name": "my-mcp-service",
#         "status": "running",
#         "port": 8080,
#         "createdAt": 1735646400
#       }
#     ],
#     "page": 1,
#     "pageSize": 20,
#     "total": 1
#   }
# }

# Create new MCP instance
curl -X POST https://demo.mcpcan.com/market/instance/create \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "weather-service",
    "port": 8081,
    "protocol": "SSE",
    "accessType": "PROXY",
    "initScript": "npm start",
    "environmentVars": {
      "API_KEY": "your_api_key",
      "NODE_ENV": "production"
    }
  }'

```

--------------------------------

### Instance Management API

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

APIs for managing MCP service instances, including listing instances and retrieving their details.

```APIDOC
## POST /market/instance/list

### Description
Retrieves a list of MCP service instances based on provided table data.

### Method
POST

### Endpoint
/market/instance/list

### Parameters
#### Request Body
- **page** (string) - Required - The current page number.
- **pageSize** (string) - Required - The number of items per page.
- **[key: string]** (any) - Optional - Additional filtering or sorting parameters.

### Request Example
```json
{
  "page": "1",
  "pageSize": "10"
}
```

### Response
#### Success Response (200)
- **list** (List<InstanceResult>) - A list of instance objects.
- **page** (number) - The current page number.
- **pageSize** (number) - The number of items per page.
- **total** (number) - The total number of instances.

#### Response Example
```json
{
  "list": [
    {
      "instanceId": "some-id",
      "name": "Instance Name",
      "status": "running"
    }
  ],
  "page": 1,
  "pageSize": 10,
  "total": 50
}
```

## GET /market/instance/{instanceId}

### Description
Retrieves the details of a specific MCP service instance.

### Method
GET

### Endpoint
/market/instance/{instanceId}

### Parameters
#### Path Parameters
- **instanceId** (any) - Required - The ID of the instance to retrieve.

#### Request Body
- **instanceId** (any) - Required - The ID of the instance to retrieve.

### Request Example
```json
{
  "instanceId": "some-id"
}
```

### Response
#### Success Response (200)
- **[field]** (any) - Details of the instance.

#### Response Example
```json
{
  "instanceId": "some-id",
  "name": "Instance Name",
  "status": "running"
}
```
```

--------------------------------

### Protocol Buffer Definitions: Instance and Request Structures

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

These Protocol Buffer definitions specify messages for market instance management, including request structures for creating instances and defining access and protocol types. They define enums for access types and MCP protocols.

```protobuf
// backend/api/market/instance/instance.proto
syntax = "proto3";

package instance;

enum AccessType {
  AccessTypeUnknown = 0;
  DIRECT = 1;
  PROXY = 2;
  HOSTING = 3;
}

enum McpProtocol {
  McpProtocolUnknown = 0;
  SSE = 1;
  STEAMABLE_HTTP = 2;
  STDIO = 3;
}

message CreateRequest {
  string name = 1;
  int32 port = 2;
  string initScript = 3;
  AccessType accessType = 4;
  McpProtocol protocol = 5;
}

message ContainerStatus {
  string instanceId = 1;
  string containerName = 2;
  bool isReady = 3;
  string runInfo = 4;
  int64 lastCheckTime = 5;
  string error = 6;
}
```

--------------------------------

### User Authentication API - Bash

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

Demonstrates how to obtain an encryption key and log in using encrypted credentials to receive JWT tokens for API access. Requires sending POST requests to the authz endpoint.

```bash
# Get encryption key for password encryption
curl -X POST https://demo.mcpcan.com/authz/encryption-key

# Response:
# {
#   "keyId": "key-123",
#   "publicKey": "-----BEGIN PUBLIC KEY-----"...,
#   "algorithm": "RSA",
#   "issuedAt": "2025-12-31T10:00:00Z",
#   "expiresAt": "2025-12-31T11:00:00Z"
# }

# Login with encrypted password
curl -X POST https://demo.mcpcan.com/authz/login \
  -H "Content-Type: application/json" \
  -d '{ 
    "username": "admin",
    "encryptedPassword": "encrypted_password_here",
    "keyId": "key-123",
    "timestamp": "1735646400"
  }'

# Response:
# {
#   "code": 0,
#   "data": {
#     "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"...,
#     "refreshToken": "refresh_token_here",
#     "expiresIn": 3600,
#     "userInfo": {
#       "id": 1,
#       "username": "admin",
#       "fullName": "System Administrator",
#       "email": "admin@example.com",
#       "status": "enabled",
#       "roleIds": [1],
#       "roleNames": ["Administrator"]
#     }
#   }
# }
```

--------------------------------

### Build Project for Production with npm

Source: https://github.com/kritsanan1/mcpcan/blob/main/frontend/README.md

Compiles and minifies the project for production deployment. This command performs type-checking and generates optimized build artifacts.

```shell
npm run build
```

--------------------------------

### Protocol Buffer Definitions: User and Page Structures

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

These Protocol Buffer definitions outline the structure for user-related data and pagination information. They include enums for user status and messages for system users and page details, with potential for HTTP annotations for RESTful API generation.

```protobuf
// backend/api/authz/user/user.proto
syntax = "proto3";

package authz.user;

import "google/api/annotations.proto";

enum UserStatus {
  UserStatusUnspecified = 0;
  UserStatusEnabled = 1;
  UserStatusDisabled = 2;
}

message SysUser {
  int64 id = 1;
  string username = 2;
  string fullName = 3;
  string password = 4;
  string email = 5;
  string phone = 6;
  string avatar = 7;
  UserStatus status = 8;
  int64 deptId = 10;
  repeated int64 roleIds = 12;
  repeated string roleNames = 13;
  int64 createdAt = 14;
  int64 updatedAt = 15;
}

message PageInfo {
  int32 page = 1;
  int32 size = 2;
  int64 total = 3;
  int32 pages = 4;
}
```

--------------------------------

### MCP Instance Management API

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

Manages MCP service instances, including listing existing instances and creating new ones with specified configurations.

```APIDOC
## POST /market/instance/list

### Description
Retrieves a paginated list of MCP service instances.

### Method
POST

### Endpoint
/market/instance/list

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **page** (string) - Required - The page number to retrieve.
- **pageSize** (string) - Required - The number of instances per page.

### Request Example
```bash
curl -X POST https://demo.mcpcan.com/market/instance/list \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ 
    "page": "1",
    "pageSize": "20"
  }'
```

### Response
#### Success Response (200)
- **code** (integer) - Status code, 0 for success.
- **data** (object) - Contains the list of instances and pagination details.
  - **list** (array) - An array of MCP instance objects.
    - **instanceId** (string) - Unique identifier for the MCP instance.
    - **name** (string) - Name of the MCP instance.
    - **status** (string) - Current status of the instance (e.g., 'running').
    - **port** (integer) - The port the instance is accessible on.
    - **createdAt** (integer) - Timestamp when the instance was created.
  - **page** (integer) - The current page number.
  - **pageSize** (integer) - The number of instances per page.
  - **total** (integer) - The total number of instances.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "instanceId": "inst-12345",
        "name": "my-mcp-service",
        "status": "running",
        "port": 8080,
        "createdAt": 1735646400
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}
```

## POST /market/instance/create

### Description
Creates a new MCP service instance with specified configuration, environment variables, and startup script.

### Method
POST

### Endpoint
/market/instance/create

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name for the new MCP instance.
- **port** (integer) - Required - The port number for the instance.
- **protocol** (string) - Optional - The communication protocol (e.g., 'SSE').
- **accessType** (string) - Optional - The access type (e.g., 'PROXY').
- **initScript** (string) - Optional - The command or script to initialize the service.
- **environmentVars** (object) - Optional - Key-value pairs for environment variables.
  - **key** (string) - Environment variable name.
  - **value** (string) - Environment variable value.

### Request Example
```bash
curl -X POST https://demo.mcpcan.com/market/instance/create \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "weather-service",
    "port": 8081,
    "protocol": "SSE",
    "accessType": "PROXY",
    "initScript": "npm start",
    "environmentVars": {
      "API_KEY": "your_api_key",
      "NODE_ENV": "production"
    }
  }'
```

### Response
#### Success Response (200)
Details of the created MCP instance (structure may vary, typically includes instance ID and configuration).

#### Response Example
(Response details not provided in source text, assumed to return created instance object)
```

--------------------------------

### Frontend Testing with pnpm

Source: https://github.com/kritsanan1/mcpcan/blob/main/CONTRIBUTING.md

Executes frontend tests using pnpm, including standard tests, coverage reporting, and end-to-end (e2e) tests. Navigate to the 'web' directory before running these commands.

```bash
cd web
pnpm test
pnpm test:coverage
pnpm test:e2e
```

--------------------------------

### Lint Code with ESLint using npm

Source: https://github.com/kritsanan1/mcpcan/blob/main/frontend/README.md

Runs ESLint to check the code for potential errors and enforce coding standards. This helps maintain code quality and consistency.

```shell
npm run lint
```

--------------------------------

### Authentication API

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

APIs for user authentication, including login, token refresh, and logout.

```APIDOC
## POST /authz/login

### Description
Logs in a user with their credentials.

### Method
POST

### Endpoint
/authz/login

### Parameters
#### Request Body
- **username** (string) - Required - The user's username.
- **encryptedPassword** (string) - Required - The user's encrypted password.
- **keyId** (string) - Optional - The ID of the key used for encryption.
- **timestamp** (string) - Optional - The timestamp of the login request.

### Request Example
```json
{
  "username": "testuser",
  "encryptedPassword": "hashed_password",
  "keyId": "key123",
  "timestamp": "2023-10-27T10:00:00Z"
}
```

### Response
#### Success Response (200)
- **token** (string) - The authentication token.
- **refreshToken** (string) - The refresh token.
- **userInfo** (UserInfo) - Information about the logged-in user.
- **expiresIn** (number) - The expiration time of the token in seconds.

#### Response Example
```json
{
  "token": "jwt.token.here",
  "refreshToken": "refresh.token.here",
  "userInfo": {
    "userId": "user123",
    "username": "testuser"
  },
  "expiresIn": 3600
}
```

## POST /authz/refresh

### Description
Refreshes the authentication token using a refresh token.

### Method
POST

### Endpoint
/authz/refresh

### Parameters
#### Request Body
- **refreshToken** (string) - Required - The refresh token.

### Request Example
```json
{
  "refreshToken": "refresh.token.here"
}
```

### Response
#### Success Response (200)
- **token** (string) - The new authentication token.
- **refreshToken** (string) - The new refresh token.
- **userInfo** (UserInfo) - Information about the user.
- **expiresIn** (number) - The expiration time of the token in seconds.

#### Response Example
```json
{
  "token": "new.jwt.token.here",
  "refreshToken": "new.refresh.token.here",
  "userInfo": {
    "userId": "user123",
    "username": "testuser"
  },
  "expiresIn": 3600
}
```

## POST /authz/logout

### Description
Logs out the current user.

### Method
POST

### Endpoint
/authz/logout

### Parameters
#### Query Parameters
- **params** (LoginOutParams) - Required - Parameters for logout.

### Request Example
```json
{
  "userId": "user123"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of logout.

#### Response Example
```json
{
  "message": "Successfully logged out."
}
```
```

--------------------------------

### Instance Lifecycle Operations with TypeScript

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

Manages MCP instance states including stopping, restarting, deleting, and retrieving logs using the InstanceAPI. Also demonstrates creating an instance from an OpenAPI specification. Relies on the '@/api/mcp/instance' module.

```typescript
import { InstanceAPI } from '@/api/mcp/instance'

// Stop an instance
const stopInstance = async (instanceId: string) => {
  try {
    await InstanceAPI.stop({ instanceId })
    console.log('Instance stopped successfully')
  } catch (error) {
    console.error('Failed to stop instance:', error)
  }
}

// Restart an instance
const restartInstance = async (instanceId: string) => {
  await InstanceAPI.restart({ instanceId })
}

// Delete an instance
const deleteInstance = async (instanceId: string) => {
  await InstanceAPI.delete(instanceId)
}

// Get instance logs
const getInstanceLogs = async (instanceId: string, lines: number = 100) => {
  const response = await InstanceAPI.logs({
    instanceId,
    lines,
    since: '1h' // Last 1 hour
  })
  console.log('Logs:', response.data)
}

// Create instance from OpenAPI specification
const createFromOpenAPI = async () => {
  const response = await InstanceAPI.createByOpenAPI({
    name: 'openapi-service',
    openapiUrl: 'https://api.example.com/openapi.json',
    port: 8082,
    authentication: {
      type: 'bearer',
      token: 'api_token_here'
    }
  })
  return response.data.instanceId
}
```

--------------------------------

### Token Management with TypeScript

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

Provides functions for managing access tokens for MCP instances, including listing, creating/updating, enabling/disabling authentication, deleting tokens, and retrieving gateway logs by token. Utilizes TokenAPI and InstanceAPI.

```typescript
import { TokenAPI } from '@/api/mcp/instance'
import { InstanceAPI } from '@/api/mcp/instance'

// List tokens for an instance
const listTokens = async (instanceId: string) => {
  const response = await TokenAPI.list({
    page: '1',
    pageSize: '50',
    instanceId
  })
  return response.data.list
}

// Create or update instance tokens
const updateInstanceTokens = async (instanceId: string) => {
  await InstanceAPI.updateInstanceTokens({
    instanceId,
    tokens: [
      {
        token: 'mcp_token_abc123',
        expireAt: Math.floor(Date.now() / 1000) + 86400 * 30, // 30 days
        publishAt: Math.floor(Date.now() / 1000),
        usages: ['read', 'write', 'execute']
      }
    ]
  })
}

// Enable/disable token authentication
const toggleTokenAuth = async (instanceId: string, enabled: boolean) => {
  await InstanceAPI.updateTokenStatus({
    instanceId,
    enabledToken: enabled
  })
}

// Delete a token
const deleteToken = async (tokenId: string) => {
  await TokenAPI.delete({ tokenId })
}

// Get gateway logs by token
const getTokenLogs = async (token: string) => {
  const response = await InstanceAPI.logsByToken({
    token,
    page: '1',
    pageSize: '100',
    startTime: Date.now() - 3600000, // Last hour
    endTime: Date.now()
  })
  return response.data.list
}
```

--------------------------------

### Instance Lifecycle Operations

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

APIs to control the lifecycle of MCP instances, including stopping, restarting, deleting, and retrieving logs.

```APIDOC
## Instance Lifecycle Operations

### Stop Instance

#### Method
POST

#### Endpoint
`/instance/stop`

#### Parameters
##### Request Body
- **instanceId** (string) - Required - The ID of the instance to stop.

### Restart Instance

#### Method
POST

#### Endpoint
`/instance/restart`

#### Parameters
##### Request Body
- **instanceId** (string) - Required - The ID of the instance to restart.

### Delete Instance

#### Method
POST

#### Endpoint
`/instance/delete`

#### Parameters
##### Request Body
- **instanceId** (string) - Required - The ID of the instance to delete.

### Get Instance Logs

#### Method
POST

#### Endpoint
`/instance/logs`

#### Parameters
##### Request Body
- **instanceId** (string) - Required - The ID of the instance for which to retrieve logs.
- **lines** (number) - Optional - The number of log lines to retrieve. Defaults to 100.
- **since** (string) - Optional - Retrieve logs since a specific time (e.g., '1h' for last hour).

### Create Instance by OpenAPI

#### Method
POST

#### Endpoint
`/instance/createByOpenAPI`

#### Parameters
##### Request Body
- **name** (string) - Required - The name for the new instance.
- **openapiUrl** (string) - Required - URL to the OpenAPI specification.
- **port** (number) - Required - The port the service will listen on.
- **authentication** (object) - Required - Authentication details for accessing the OpenAPI spec.
  - **type** (string) - Required - Authentication type (e.g., 'bearer').
  - **token** (string) - Required - The authentication token.

#### Response Example (Create Instance)
```json
{
  "data": {
    "instanceId": "new-instance-id-123"
  }
}
```
```

--------------------------------

### User Management API

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

Provides endpoints for creating, retrieving, updating, listing, and deleting user accounts, including role assignments and status management.

```APIDOC
## POST /authz/users

### Description
Creates a new user account in the system.

### Method
POST

### Endpoint
/authz/users

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **username** (string) - Required - The username for the new account.
- **fullName** (string) - Required - The full name of the user.
- **email** (string) - Required - The email address of the user.
- **password** (string) - Required - The user's password.
- **phone** (string) - Optional - The user's phone number.
- **status** (integer) - Required - The status of the user account (e.g., 1 for enabled).
- **deptId** (integer) - Optional - The ID of the department the user belongs to.
- **roleIds** (array of integers) - Required - A list of role IDs to assign to the user.

### Request Example
```json
{
  "username": "john.doe",
  "fullName": "John Doe",
  "email": "john.doe@example.com",
  "password": "secure_password_123",
  "phone": "+1234567890",
  "status": 1,
  "deptId": 10,
  "roleIds": [2, 3]
}
```

### Response
#### Success Response (200)
Details of the created user (structure may vary, typically includes user ID and basic info).

#### Response Example
(Response details not provided in source text, assumed to return created user object)

## PUT /authz/users/{userId}

### Description
Updates the information for an existing user account.

### Method
PUT

### Endpoint
/authz/users/{userId}

### Parameters
#### Path Parameters
- **userId** (integer) - Required - The ID of the user to update.

#### Query Parameters
None

#### Request Body
- **fullName** (string) - Optional - The updated full name of the user.
- **email** (string) - Optional - The updated email address of the user.
- **status** (integer) - Optional - The updated status of the user account.
- **roleIds** (array of integers) - Optional - The updated list of role IDs to assign to the user.

### Request Example
```json
{
  "fullName": "John Smith",
  "email": "john.smith@example.com",
  "status": 1,
  "roleIds": [2, 3, 4]
}
```

### Response
#### Success Response (200)
Indicates successful update (response body may be empty or contain updated user info).

### Response Example
(Response details not provided in source text)

## GET /authz/users/{userId}

### Description
Retrieves detailed information for a specific user account.

### Method
GET

### Endpoint
/authz/users/{userId}

### Parameters
#### Path Parameters
- **userId** (integer) - Required - The ID of the user to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
# Example assuming a request function is available
getUser(123)
```

### Response
#### Success Response (200)
- **(object)** - User object containing detailed information.

#### Response Example
(Response details not provided in source text, assumed to return user object similar to login response userInfo)

## POST /authz/users/list

### Description
Retrieves a paginated list of users, with optional filtering by status.

### Method
POST

### Endpoint
/authz/users/list

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **page** (integer) - Required - The page number to retrieve.
- **pageSize** (integer) - Required - The number of users per page.
- **status** (integer) - Optional - Filter users by their status.

### Request Example
```json
{
  "page": 1,
  "pageSize": 10,
  "status": 1
}
```

### Response
#### Success Response (200)
- **list** (array) - An array of user objects.
- **page** (integer) - The current page number.
- **pageSize** (integer) - The number of users per page.
- **total** (integer) - The total number of users matching the criteria.

#### Response Example
```json
{
  "list": [
    // user objects...
  ],
  "page": 1,
  "pageSize": 10,
  "total": 100
}
```

## DELETE /authz/users/{userId}

### Description
Deletes a specific user account from the system.

### Method
DELETE

### Endpoint
/authz/users/{userId}

### Parameters
#### Path Parameters
- **userId** (integer) - Required - The ID of the user to delete.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
# Example assuming a request function is available
deleteUser(123)
```

### Response
#### Success Response (200)
Indicates successful deletion (response body may be empty).

#### Response Example
(Response details not provided in source text)
```

--------------------------------

### User Management API - TypeScript

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

Provides TypeScript functions for frontend integration to manage user accounts, including creation, updates, retrieval, listing with pagination, and deletion. It utilizes a request utility for API calls.

```typescript
// Frontend TypeScript example
import request from '@/utils/request'

// Create new user
const createUser = async () => {
  try {
    const response = await request({
      url: '/authz/users',
      method: 'POST',
      data: {
        username: 'john.doe',
        fullName: 'John Doe',
        email: 'john.doe@example.com',
        password: 'secure_password_123',
        phone: '+1234567890',
        status: 1, // UserStatusEnabled
        deptId: 10,
        roleIds: [2, 3]
      }
    })
    console.log('User created:', response.data)
  } catch (error) {
    console.error('Failed to create user:', error)
  }
}

// Update user information
const updateUser = async (userId: number) => {
  await request({
    url: `/authz/users/${userId}`,
    method: 'PUT',
    data: {
      fullName: 'John Smith',
      email: 'john.smith@example.com',
      status: 1,
      roleIds: [2, 3, 4]
    }
  })
}

// Get user by ID
const getUser = async (userId: number) => {
  const response = await request({
    url: `/authz/users/${userId}`,
    method: 'GET'
  })
  return response.data
}

// List users with pagination
const listUsers = async (page: number, pageSize: number) => {
  const response = await request({
    url: '/authz/users/list',
    method: 'POST',
    data: { page, pageSize, status: 1 }
  })
  return response.data // { list: [], page: 1, pageSize: 10, total: 100 }
}

// Delete user
const deleteUser = async (userId: number) => {
  await request({
    url: `/authz/users/${userId}`,
    method: 'DELETE'
  })
}
```

--------------------------------

### User Authentication API

Source: https://context7.com/kritsanan1/mcpcan/llms.txt

Handles user authentication by obtaining encryption keys and logging in with encrypted credentials to receive JWT tokens for API access.

```APIDOC
## POST /authz/encryption-key

### Description
Retrieves the public key and associated information required to encrypt passwords before sending them to the login endpoint.

### Method
POST

### Endpoint
/authz/encryption-key

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X POST https://demo.mcpcan.com/authz/encryption-key
```

### Response
#### Success Response (200)
- **keyId** (string) - Identifier for the encryption key.
- **publicKey** (string) - The public key in PEM format.
- **algorithm** (string) - The encryption algorithm used (e.g., RSA).
- **issuedAt** (string) - Timestamp when the key was issued.
- **expiresAt** (string) - Timestamp when the key expires.

#### Response Example
```json
{
  "keyId": "key-123",
  "publicKey": "-----BEGIN PUBLIC KEY-----...",
  "algorithm": "RSA",
  "issuedAt": "2025-12-31T10:00:00Z",
  "expiresAt": "2025-12-31T11:00:00Z"
}
```

## POST /authz/login

### Description
Logs in a user with their username and an encrypted password, returning JWT tokens and user information upon successful authentication.

### Method
POST

### Endpoint
/authz/login

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **username** (string) - The user's login username.
- **encryptedPassword** (string) - The password, encrypted using the public key obtained from the `/authz/encryption-key` endpoint.
- **keyId** (string) - The identifier of the encryption key used.
- **timestamp** (string) - The Unix timestamp of the login request, used for request validation.

### Request Example
```bash
curl -X POST https://demo.mcpcan.com/authz/login \
  -H "Content-Type: application/json" \
  -d '{ 
    "username": "admin",
    "encryptedPassword": "encrypted_password_here",
    "keyId": "key-123",
    "timestamp": "1735646400"
  }'
```

### Response
#### Success Response (200)
- **code** (integer) - Status code, 0 for success.
- **data** (object) - Contains authentication tokens and user details.
  - **token** (string) - The JWT access token.
  - **refreshToken** (string) - The refresh token for obtaining new access tokens.
  - **expiresIn** (integer) - The expiration time of the access token in seconds.
  - **userInfo** (object) - Contains information about the logged-in user.
    - **id** (integer) - User's unique identifier.
    - **username** (string) - User's username.
    - **fullName** (string) - User's full name.
    - **email** (string) - User's email address.
    - **status** (string) - User's account status (e.g., 'enabled').
    - **roleIds** (array of integers) - List of role IDs assigned to the user.
    - **roleNames** (array of strings) - List of role names assigned to the user.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "refresh_token_here",
    "expiresIn": 3600,
    "userInfo": {
      "id": 1,
      "username": "admin",
      "fullName": "System Administrator",
      "email": "admin@example.com",
      "status": "enabled",
      "roleIds": [1],
      "roleNames": ["Administrator"]
    }
  }
}
```
```