Skip to content

Commit e5a4ccd

Browse files
yyyyaaayyyyaaa
authored
docs: add MCP server docs (#7)
1 parent c3c9680 commit e5a4ccd

File tree

6 files changed

+286
-202
lines changed

6 files changed

+286
-202
lines changed

‎.github/workflows/docs.yml

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'docs/**'
9+
- 'learn/**'
10+
- '.github/workflows/docs.yml'
11+
# Allow manual triggering
12+
workflow_dispatch:
13+
14+
# Prevent concurrent deployments to avoid conflicts
15+
concurrency:
16+
group: docs-deploy-${{ github.ref }}
17+
cancel-in-progress: true
18+
19+
env:
20+
# Repository specific variables
21+
REPO_NAME: agentic-tools
22+
DOCS_DEST_PATH: pages/mcp-server
23+
LEARN_DEST_PATH: src/data/learn/mcp-server
24+
NODE_VERSION: '20'
25+
26+
jobs:
27+
docs-deploy:
28+
name: Sync and Deploy Documentation
29+
runs-on: ubuntu-latest
30+
timeout-minutes: 15
31+
32+
steps:
33+
- name: Checkout Repository
34+
uses: actions/checkout@v4
35+
with:
36+
fetch-depth: 1
37+
38+
- name: Setup Node.js
39+
uses: actions/setup-node@v4
40+
with:
41+
node-version: ${{ env.NODE_VERSION }}
42+
cache: 'yarn'
43+
44+
- name: Clone docs repository
45+
run: git clone https://x-access-token:${{ secrets.GH_HYPERWEB_PAT }}@github.com/hyperweb-io/docs.hyperweb.io.git external-docs
46+
47+
- name: Sync the docs and build
48+
run: |
49+
rsync -av --delete ./docs/ ./external-docs/${{ env.DOCS_DEST_PATH }}/
50+
cd external-docs
51+
yarn install
52+
yarn export
53+
54+
- name: Git push
55+
run: |
56+
cd external-docs
57+
git config user.name 'GitHub Action'
58+
git config user.email '[email protected]'
59+
git add .
60+
if git diff --cached --quiet; then
61+
echo "No changes to commit."
62+
else
63+
git commit -m "Automated: Update ${{ env.REPO_NAME }} documentation"
64+
git push
65+
fi

‎docs/_meta.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"index": "Getting Started",
3+
"references": "API Reference"
4+
}

‎docs/index.mdx

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Getting Started with @hyperweb/mcp-server
2+
3+
Welcome to the documentation for the Hyperweb MCP Server (`@hyperweb/mcp-server`). This server implements the Model Context Protocol (MCP) to help you use Hyperweb platform tools more effectively and easily with AI agents.
4+
5+
## Overview
6+
7+
The Agentic Tools MCP Server, also known as `@hyperweb/mcp-server`, provides a suite of functionalities focused on Cosmos SDK based chains and the broader interchain ecosystem. It allows for interactions with:
8+
9+
- **Interchain Kit**: Tools related to interchain standards and protocols.
10+
- **Chain Registry**: Accessing and managing information about different chains.
11+
- **InterchainJS**: Leveraging JavaScript libraries for interchain operations.
12+
- **Starship**: Interacting with Starship, a unified deployment environment for Cosmos.
13+
14+
This server aims to simplify common developer workflows and provide programmatic access to essential data and operations within the Hyperweb and Cosmos environments.
15+
16+
## Setup
17+
18+
To run the Hyperweb MCP server using npx, use the following command in your terminal:
19+
20+
```bash
21+
npx -y @hyperweb/mcp-server@latest
22+
```
23+
24+
This command will download and run the latest version of the server.
25+
26+
## Usage with AI Clients (Cursor or Claude Desktop)
27+
28+
To integrate the Hyperweb MCP Server with AI clients like Cursor or Claude Desktop, you need to add the following configuration to your client's settings. This allows the AI client to discover and use the tools provided by this MCP server.
29+
30+
For more information, you can refer to the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol) or the [Claude Desktop MCP guide](https://modelcontextprotocol.io/quickstart/user).
31+
32+
**Standard Configuration:**
33+
34+
```json
35+
{
36+
"mcpServers": {
37+
"hyperweb-mcp-server": {
38+
"command": "npx",
39+
"args": ["-y", "@hyperweb/mcp-server@latest"]
40+
}
41+
}
42+
}
43+
```
44+
45+
**Windows Alternative Configuration:**
46+
47+
If you are on Windows, you might need to use this alternative configuration:
48+
49+
```json
50+
{
51+
"mcpServers": {
52+
"hyperweb-mcp-server": {
53+
"command": "cmd",
54+
"args": ["/k", "npx", "-y", "@hyperweb/mcp-server@latest"]
55+
}
56+
}
57+
}
58+
```
59+
60+
## Available Tools
61+
62+
This server provides a range of tools to assist with development in the Hyperweb and Cosmos ecosystems. For a detailed list of all available tools, their descriptions, and parameters, please refer to the [API Reference](./references).
63+
64+
Key areas covered by the tools include:
65+
66+
- Chain Registry interactions (`useChainRegistry`)
67+
- Interchain Kit usage and migration (`useInterchainKit`, `migrateFromCosmosKitToInterchainKit`)
68+
- InterchainJS usage and migration (`useInterchainjs`, `migrateToInterchainjs`)
69+
- Starship environment setup and configuration (`setupStarship`, `generateStarshipConfig`, `verifyStarshipConfig`)
70+
71+
## Development
72+
73+
If you plan to contribute or modify the server:
74+
75+
### Available Scripts
76+
77+
- `pnpm build` - Build the project and copy prompts to build directory
78+
- `pnpm clean` - Clean build artifacts
79+
- `pnpm test` - Run tests
80+
- `pnpm inspector` - Run the MCP inspector with the server
81+
- `pnpm format` - Format code using Biome
82+
- `pnpm lint` - Lint code using Biome
83+
84+
### Key Technologies
85+
86+
- **TypeScript**: For static typing and modern JavaScript features.
87+
- **Biome**: For linting and formatting.
88+
- **Model Context Protocol SDK**: For AI model interactions.
89+
- **Zod**: For runtime type validation.

‎docs/references.mdx

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# API Reference
2+
3+
This document provides a detailed reference for the tools available in the Agentic Tools MCP Server. Each tool is designed to facilitate interactions with various components of the Hyperweb and Cosmos ecosystems.
4+
5+
## Chain Registry Tools
6+
7+
Tools for accessing and managing information from chain registries.
8+
9+
### `useChainRegistry`
10+
11+
- **Description**: This tool provides comprehensive examples and usage patterns for the Chain Registry, call this tool for any Chain Registry implementation guidance.
12+
- **Source**: `src/chain-registry/tools/use-chain-registry.ts`
13+
- **Parameters**:
14+
- `majorVersion` (enum: `v1` | `v2`, required): The major version of the Chain Registry to use.
15+
- **Output**: Provides text content with examples and usage patterns for the specified Chain Registry version.
16+
17+
## Interchain Kit Tools
18+
19+
Tools related to Interchain Kit, including usage guidance and migration assistance.
20+
21+
### `useInterchainKit`
22+
23+
- **Description**: This tool provides comprehensive examples and usage patterns for the Interchain Kit, call this tool for any Interchain Kit implementation guidance.
24+
- **Source**: `src/interchain-kit/tools/use-interchain-kit.ts`
25+
- **Parameters**:
26+
- `framework` (enum: `react` | `vue`, required): The frontend framework of the project.
27+
- **Output**: Provides text content with examples and usage patterns for Interchain Kit tailored to the specified framework.
28+
29+
### `migrateFromCosmosKitToInterchainKit`
30+
31+
- **Description**: Migrate a project from CosmosKit to InterchainKit using the provided migration guide. The user's code to be migrated is expected to be available in the IDE context.
32+
- **Source**: `src/interchain-kit/tools/migrate-from-cosmos-kit-to-interchain-kit.ts`
33+
- **Parameters**: None.
34+
- **Output**: Provides text content containing the CosmosKit to InterchainKit migration guide.
35+
36+
## InterchainJS Tools
37+
38+
Tools for leveraging InterchainJS, including usage guidance and migration assistance from CosmJS.
39+
40+
### `useInterchainjs`
41+
42+
- **Description**: This tool provides comprehensive examples and usage patterns for the InterchainJS library, call this tool for any InterchainJS implementation guidance.
43+
- **Source**: `src/interchainjs/tools/use-interchainjs.ts`
44+
- **Parameters**: None.
45+
- **Output**: Provides text content with examples and usage patterns for the InterchainJS library.
46+
47+
### `migrateToInterchainjs`
48+
49+
- **Description**: Migrate CosmJS code to InterchainJS. REQUIRES the project's package manager (npm, yarn, or pnpm) to be correctly specified for proper dependency installation commands.
50+
- **Source**: `src/interchainjs/tools/migrate-to-interchainjs.ts`
51+
- **Parameters**:
52+
- `packageManager` (enum: `npm` | `yarn` | `pnpm`, required): The package manager detected in the target project. This value MUST be correctly determined and provided by the caller.
53+
- **Output**: Provides text content containing a migration guide from CosmJS to InterchainJS, including API mappings and code examples, tailored for the specified package manager.
54+
55+
## Starship Tools
56+
57+
Tools for interacting with Starship, the unified development and testing environment for Cosmos chains. This includes setup assistance and configuration generation.
58+
59+
### `setupStarship`
60+
61+
- **Description**: Setup and use Starship in a project.
62+
- **Source**: `src/starship/tools/starship-setup.ts`
63+
- **Parameters**: None.
64+
- **Output**: Provides text content with a guide for setting up Starship.
65+
66+
### `generateStarshipConfig`
67+
68+
- **Description**: Generates a Starship configuration file in YAML format based on detailed input options then creates the file (e.g., `starship/config.yaml`) in the workspace.
69+
- **Source**: `src/starship/tools/starship-config-gen.ts`
70+
- **Parameters (StarshipConfigInput)**:
71+
- `configFilePath` (string, required): The absolute path to the Starship configuration file (e.g., `<current_working_directory>/starship/config.yaml`).
72+
- `configName` (string, optional, default: "starship"): Top-level configuration name.
73+
- `configVersion` (string, optional, default: "1.6.0"): Top-level configuration version.
74+
- `chains` (array of ChainConfig, required, min: 1): List of chain configurations. Each `ChainConfig` includes:
75+
- `id` (string, required): Unique identifier for the chain.
76+
- `name` (string, required): Type of chain (e.g., 'osmosis', 'custom').
77+
- `numValidators` (integer, required, positive): Number of validators.
78+
- `image` (string, optional): Override default Docker image.
79+
- `home` (string, optional): Home directory path (for `name: 'custom'`).
80+
- `binary` (string, optional): Binary name (for `name: 'custom'`).
81+
- `prefix` (string, optional): Address prefix (for `name: 'custom'`).
82+
- `denom` (string, optional): Primary denomination (for `name: 'custom'`).
83+
- `coins` (string, optional): Genesis coins.
84+
- `hdPath` (string, optional): HD path.
85+
- `coinType` (integer, optional): Coin type.
86+
- `repo` (string URL, optional): Git repository URL.
87+
- `ports` (object, optional): Port forwarding (`rest`, `rpc`, `grpc`, `faucet`, `exposer`).
88+
- `resources` (object, optional): CPU/memory allocation (`cpu`, `memory`).
89+
- `faucet` (object, optional): Faucet config (`enabled`, `type`, `image`, `concurrency`, `resources`).
90+
- `build` (object, optional): On-the-fly build config (`enabled`, `source`).
91+
- `upgrade` (object, optional): Upgrade prep config (`enabled`, `type`, `genesis`, `upgrades` array).
92+
- `genesis` (object, optional): `genesis.json` patches (`app_state`).
93+
- `scripts` (object, optional): Override setup scripts.
94+
- `cometmock` (object, optional): CometMock config (`enabled`, `image`).
95+
- `env` (array of EnvVar, optional): Custom environment variables (`name`, `value`).
96+
- `ics` (object, optional): ICS config for consumer chains (`enabled`, `provider`).
97+
- `balances` (array of BalanceEntry, optional): Initial balances (`address`, `amount`).
98+
- `readinessProbe` (object, optional): Custom readiness probe.
99+
- `config` (object, optional): Ethereum-specific config (if `name` is 'ethereum').
100+
- `relayers` (array of RelayerConfig, optional): List of relayer configurations. Each `RelayerConfig` includes:
101+
- `name` (string, required): Name for the relayer instance.
102+
- `type` (enum: `hermes` | `ts-relayer` | `go-relayer` | `neutron-query-relayer`, required): Type of relayer.
103+
- `image` (string, optional): Override default Docker image.
104+
- `replicas` (integer, optional, default: 1): Number of replicas (currently 1).
105+
- `chains` (array of string, required, min: 2): Chain IDs to connect.
106+
- `config` (object, optional): Hermes specific `config.toml` overrides.
107+
- `ports` (object, optional): Hermes specific port forwarding (`rest`, `exposer`).
108+
- `ics` (object, optional): Hermes specific ICS setup.
109+
- `explorer` (ExplorerConfig, optional): Explorer configuration (`enabled`, `type`, `ports`, `resources`, `image`).
110+
- `registry` (RegistryConfig, optional): Registry service configuration (`enabled`, `localhost`, `ports`, `resources`, `image`).
111+
- **Output**: Text confirmation with the generated YAML content and writes the file to the specified `configFilePath`.
112+
113+
### `verifyStarshipConfig`
114+
115+
- **Description**: Parses and validates a Starship configuration YAML string against the known schema.
116+
- **Source**: `src/starship/tools/starship-config-gen.ts`
117+
- **Parameters (VerifyStarshipConfigInput)**:
118+
- `configFilePath` (string, required): The absolute path to the Starship configuration file.
119+
- `yamlContent` (string, required): The Starship configuration content in YAML format as a string.
120+
- **Output**: Text indicating if the configuration is valid or invalid, with error details if invalid.
121+
122+
## Utility Tools
123+
124+
_(Placeholder: Currently no tools from `src/utils/` are explicitly registered as MCP tools in the provided snippets. If `createTool` in `src/utils/tool-helpers.js` is used to register tools directly or if other files in `utils` register tools, they should be added here.)_
125+
126+
---
127+
128+
_Note: The parameters listed are based on the Zod schemas in the tool definitions. For complex object parameters like `ChainConfig` or `RelayerConfig` within `generateStarshipConfig`, refer to the source file (`src/starship/tools/starship-config-gen.ts`) for the full nested structure and descriptions of each field._

‎docs/roadmap.md

Lines changed: 0 additions & 52 deletions
This file was deleted.

0 commit comments

Comments
 (0)