Skip to content

Commit c61db5e

Browse files
authored
Merge pull request #1 from metacontract/dev
release v0.1
2 parents a3c88c7 + a623416 commit c61db5e

File tree

22 files changed

+2228
-534
lines changed

22 files changed

+2228
-534
lines changed

.amf/knowledge/note/project.md

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,11 @@
77
* **Target Framework:** `metacontract` (mc) - A Foundry-based framework implementing ERC-7546 (Upgradeable Clone for Scalable Contracts) focusing on upgradeability, modularity, scalability, and testability. Optimized for AI integration and DevOps efficiency.
88
* **Protocol:** Model Context Protocol (MCP) - An open protocol standardizing interactions between AI applications (clients/hosts like IDEs) and external tools/data sources (servers like `mc-mcp`).
99
* **Core Functionality (MCP Tools):** Implemented using `rmcp` SDK's `#[tool]` and `#[tool(tool_box)]` annotations.
10-
* **`forge_test`:** Run `forge test` in the workspace.
11-
* **`search_docs`:** Semantic search over `mc` documentation and user-configured sources, returning structured JSON (`Vec<SearchResult>`).
10+
* **Naming convention:** All MCP tools should be named with the `mc_` prefix followed by the function name (e.g., `mc_setup`, `mc_deploy`, `mc_upgrade`, `mc_lint`, `mc_test`, `mc_search_docs`).
11+
* **Deploy/Upgrade tool dry-run support:** `mc_deploy` and `mc_upgrade` must support dry-run mode (default), toggled by the `broadcast: true` argument. The script path is configured via `mcp_config.toml ([scripts].deploy / [scripts].upgrade)`. Without `broadcast: true`, the tool should simulate the operation (dry-run); with `broadcast: true`, it should execute the actual deployment/upgrade (requires `rpc_url` and `private_key_env_var` to be set in `mcp_config.toml` under `[scripts]`).
12+
* **`mc_test`:** Run `forge test` in the workspace.
13+
* **`mc_search_docs`:** Semantic search over `mc` documentation and user-configured sources, returning structured JSON (`Vec<SearchResult>`).
14+
* **`mc_setup`**: Initialize a new Foundry project using the `metacontract/template`. Requires an empty directory.
1215

1316
## 2. Technology Stack
1417

@@ -19,7 +22,7 @@
1922
* **Text Embedding:** Local Sentence Transformer (e.g., all-MiniLM-L6-v2) via `fastembed-rs`
2023
* **Configuration:** figment
2124
* **Logging:** tracing
22-
* **Error Handling:** anyhow, thiserror
25+
* **Error Handling:** Result<T, E>, thiserror, anyhow
2326
* **Markdown Parsing:** comrak
2427
* **Dependency Injection:** Manual DI
2528

@@ -47,7 +50,7 @@
4750
* **Error Handling:** Result<T, E>, thiserror, anyhow
4851
* **Persistence:** Local file system for cache, Qdrant for vector index
4952
* **Transport:** stdio (primary), SSE (future)
50-
* **Testing:** TDD, unit/integration tests, testcontainers for Qdrant
53+
* **Testing:** TDD, unit/integration tests. Qdrant integration tests utilize `testcontainers` for isolated and stable execution. Unit tests involving `forge` use mock scripts (`tests/mock_bin/forge`).
5154
* **CI/CD:** GitHub Actions (build, test, prebuilt index build & upload)
5255
* Artifacts: prebuilt_index.jsonl.gz (compressed, not in git)
5356
* Download logic: always fetches latest from GitHub Releases if not present

.github/workflows/ci.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@ name: CI
22

33
on:
44
push:
5-
branches: [ main, develop ]
5+
branches: [ main ]
66
pull_request:
7-
branches: [ main, develop ]
7+
branches: [ main, dev ]
88

99
jobs:
1010
build-and-test:

.gitignore

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,8 @@
1818
artifacts/
1919
*.jsonl
2020
*.jsonl.gz
21+
22+
# Local template cache
23+
.cache/
24+
.cache/*
25+
.cache/mc-template/

Cargo.lock

Lines changed: 11 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Cargo.toml

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "mc-mcp"
3-
version = "0.1.0"
3+
version = "0.1.4"
44
edition = "2021"
55
authors = ["ea <ecdysis-xyz@proton.me>", "kai <kai.hiroi@pm.me>"]
66
description = "A Model Context Protocol (MCP) server for metacontract smart contract development."
@@ -39,6 +39,7 @@ figment = { version = "0.10", features = ["env", "toml", "test"] }
3939
# Added for the new features
4040
downcast-rs = "1.2.1"
4141
env_logger = "0.11.3"
42+
directories = "5.0"
4243
# Required by src files, moved from dev-dependencies
4344
testcontainers = { version = "0.23.3" }
4445
testcontainers-modules = { version = "0.11.6" }
@@ -65,9 +66,7 @@ wiremock = "0.6.1"
6566
tonic = "0.12"
6667
# serial_test = "3.1.1" # Moved to dependencies
6768
# mockall = "0.12" # Moved to dependencies
69+
testcontainers = "0.23"
6870

6971
[build-dependencies]
7072
# Add build dependencies if needed
71-
72-
[alias]
73-
build-index = "run --bin build_index --"

Makefile

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
test-all: cache-template
2+
cargo test --all --release -- --test-threads=1
3+
4+
test-lib: cache-template
5+
find .fastembed_cache -name '*.lock' -delete || true
6+
cargo test --lib -- --test-threads=1
7+
8+
test-integration: cache-template
9+
cargo test --test vector_db_integration -- --test-threads=1
10+
11+
clean-cache:
12+
rm -rf .fastembed_cache
13+
14+
fix:
15+
cargo fix --allow-dirty --allow-staged
16+
17+
coverage:
18+
cargo tarpaulin --out Html --output-dir target/tarpaulin
19+
20+
build-index:
21+
run --bin build_index -- --index-name=test_index
22+
23+
cache-template:
24+
@if [ ! -d .cache/mc-template/.git ]; then \
25+
git clone --depth 1 https://github.com/metacontract/template.git .cache/mc-template; \
26+
else \
27+
cd .cache/mc-template && git pull; \
28+
fi
29+
30+
test-setup:
31+
make cache-template
32+
cp -r .cache/mc-template ./test-tmp-template

README.md

Lines changed: 61 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,12 @@ A Model Context Protocol (MCP) server for the [metacontract (mc)](https://github
99
**mc-mcp** is an extensible MCP server designed for the [metacontract](https://github.com/metacontract/mc) (mc) framework.
1010
It enables AI-powered smart contract development workflows by exposing tools such as:
1111

12-
- **`forge_test`**: Run Foundry tests (`forge test`) in your workspace.
13-
- **`search_docs`**: Perform semantic search over mc documentation and user-configured sources, returning structured JSON results.
12+
- **`mc_search_docs`**: Perform semantic search over mc documentation and user-configured sources, returning structured JSON results.
13+
- **`mc_test`**: Run Foundry tests (`forge test`) in your workspace.
14+
- **`mc_setup`**: Initialize a new Foundry project using the `metacontract/template` (requires an empty directory).
15+
- **`mc_deploy`**: Deploy contracts using the script specified in `mcp_config.toml`. Supports dry-run (default) and broadcast mode (`broadcast: true` argument).
16+
- **`mc_upgrade`**: Upgrade contracts using the script specified in `mcp_config.toml`. Supports dry-run and broadcast mode.
17+
- **`mc_lint`**: (Coming Soon) Lint project files for best practices and errors.
1418

1519
---
1620

@@ -105,15 +109,18 @@ See [RooCode's documentation](https://github.com/RooVetGit/Roo-Code) for details
105109
### 5. Develop your smart contract
106110

107111
- Use your MCP-compatible Agent/IDE to interact with mc-mcp
108-
- Design, search docs, and run TDD cycles (`forge_test`, `search_docs`, etc.)
112+
- Design, search docs, and run TDD cycles (`mc_test`, `mc_search_docs`, etc.)
109113

110114
### Configuration Example
111115

112116
Create a file named `mcp_config.toml` in your project root:
113117

114118
```toml
119+
# Reference sources for semantic search
115120
[reference]
116-
prebuilt_index_path = "artifacts/prebuilt_index.jsonl.gz"
121+
# The prebuilt index is downloaded to the system cache directory by default.
122+
# You can override the path here if needed:
123+
# prebuilt_index_path = "/custom/path/to/prebuilt_index.jsonl.gz"
117124

118125
[[reference.sources]]
119126
name = "mc-docs"
@@ -129,10 +136,21 @@ path = "docs/solidity"
129136
name = "user-docs"
130137
source_type = "local"
131138
path = "docs/user"
139+
140+
# Default scripts used by tools
141+
[scripts]
142+
deploy = "scripts/Deploy.s.sol" # Used by mc_deploy
143+
upgrade = "scripts/Upgrade.s.sol" # Used by mc_upgrade
144+
145+
# Optional: Settings for broadcasting transactions (used when broadcast=true)
146+
rpc_url = "http://localhost:8545" # RPC endpoint URL
147+
private_key_env_var = "PRIVATE_KEY" # Name of the env var holding the deployer's private key
132148
```
133149

134-
- `prebuilt_index_path` ... (optional) Path to a prebuilt index (jsonl or gzipped jsonl). If set, it will be loaded and upserted into Qdrant on startup.
150+
- `prebuilt_index_path` ... (optional) Path to a prebuilt index (jsonl or gzipped jsonl). If set, it overrides the default cache location. The index will be loaded and upserted into Qdrant on startup.
135151
- Each `[[reference.sources]]` must have `name`, `source_type` (usually `local`), and `path` (relative to the execution directory).
152+
- `[scripts].deploy` and `[scripts].upgrade` specify the default Foundry script paths used by the `mc_deploy` and `mc_upgrade` tools respectively.
153+
- `[scripts].rpc_url` and `[scripts].private_key_env_var` are required when using `mc_deploy` or `mc_upgrade` with the `broadcast: true` argument. `forge` will use these to send the transaction.
136154
- All paths must exist and be directories, or indexing will fail.
137155

138156
See also: [config.rs](src/config.rs) for the full config structure.
@@ -151,9 +169,46 @@ See also: [config.rs](src/config.rs) for the full config structure.
151169
## Development
152170

153171
- **TDD**: Test-Driven Development is enforced (unit/integration tests)
154-
- **Integration tests**: Use [testcontainers](https://github.com/testcontainers/testcontainers-rs) for Qdrant
172+
- **Integration tests**: Use [testcontainers](https://github.com/testcontainers/testcontainers-rs) for Qdrant, ensuring isolated and stable test environments.
155173
- **CI/CD**: GitHub Actions for build, test, and prebuilt index artifact management
156174

175+
## Testing & Troubleshooting
176+
177+
Some tests (especially integration tests and embedding-related tests) may fail due to OS file descriptor limits or cache lock issues.
178+
179+
### Common Commands (via Makefile)
180+
181+
- **Unit tests (lib only, with cache lock cleanup, single-threaded):**
182+
```sh
183+
make test-lib
184+
```
185+
- **All tests (recommended: increase ulimit before running):**
186+
```sh
187+
ulimit -n 4096
188+
make test-all
189+
```
190+
- **Integration tests (single-threaded):**
191+
```sh
192+
make test-integration
193+
```
194+
- **Clean embedding model cache:**
195+
```sh
196+
make clean-cache
197+
```
198+
199+
### Troubleshooting
200+
201+
- **If you see `Too many open files` errors:**
202+
- Increase the file descriptor limit in your shell *before* running tests: `ulimit -n 4096`
203+
- Run tests sequentially: `cargo test -- --test-threads=1` (or use `make test-lib` / `make test-integration`)
204+
- **If you see `.lock` errors (related to embedding model cache):**
205+
- Clean the cache: `make clean-cache`
206+
- **If tests involving `forge` commands fail unexpectedly:**
207+
- Ensure the mock script setup within the specific test file (`src/main.rs` tests) is correct.
208+
- **Note:**
209+
- The Makefile provides handy shortcuts for common tasks, but some OS or CI environments may require manual adjustment of file descriptor limits (`ulimit`).
210+
- See each Makefile target for details.
211+
157212
---
158213

159214
## Task Management & Progress

mcp_config.toml

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
[reference]
2-
prebuilt_index_path = "artifacts/prebuilt_index.jsonl.gz"
2+
# Default path is now the system's cache directory (e.g., ~/.cache/mc-mcp on Linux).
3+
# You can uncomment and set a specific path if needed.
4+
# prebuilt_index_path = "artifacts/prebuilt_index.jsonl.gz"
35

46
# [[reference.sources]]
57
# name = "mc-docs"
@@ -15,3 +17,7 @@ prebuilt_index_path = "artifacts/prebuilt_index.jsonl.gz"
1517
# name = "user-docs"
1618
# source_type = "local"
1719
# path = "docs/user"
20+
21+
[scripts]
22+
deploy = "scripts/Deploy.s.sol" # Default deploy script path
23+
# upgrade = "scripts/Upgrade.s.sol" # Example for upgrade script later

0 commit comments

Comments
 (0)