Content
# Pest MCP Server
MCP server for Pest PHP testing framework documentation references
This is a TypeScript-based MCP server that provides reference information for Pest PHP testing framework documentation. It implements a Model Context Protocol (MCP) server that helps AI assistants access Pest documentation and examples directly from the official Pest documentation repository.
## Features
### Tools
- `list_pest_topics` - Get a list of all available Pest documentation topics
- `get_pest_topic_details` - Get detailed information about a specific Pest topic
- `get_pest_topic_examples` - Get usage examples for a specific Pest topic
- `search_pest_docs` - Search for topics in Pest documentation by keyword
- `list_pest_categories` - Get a list of all Pest documentation categories
### Functionality
This server fetches and caches information from:
- The official Pest documentation GitHub repository (https://github.com/pestphp/docs)
- Uses the raw Markdown files for each documentation topic
- Organizes topics by categories (Getting Started, Testing Basics, Advanced Testing, etc.)
- Caches documentation files locally to avoid repeated downloads
It provides structured data including:
- Complete topic content from Markdown files
- Categorized documentation structure (Getting Started, Testing Basics, Advanced Testing, Test Management, Extensibility, Advanced Features, Configuration & CI, Reference & Migration, News & Community)
- Extracted code examples with language detection
- Section content with headings and anchors
- Intelligent description extraction
- Background preloading of common topics
- Persistent file caching for offline usage
## Development
Install dependencies:
```bash
npm install
```
Build the server:
```bash
npm run build
```
For development with auto-rebuild:
```bash
npm run watch
```
## Usage with Augment
Once you've configured the Pest MCP server with Augment, you can use it to access Pest documentation directly in your VS Code environment. Here are some examples of how to use it:
### Listing Pest Documentation Topics
You can ask Augment to list all available Pest documentation topics:
```
What Pest documentation topics are available?
```
Or list topics by category:
```
What Pest documentation topics are available in the "Testing Basics" category?
```
```
Show me all the topics in the "Advanced Testing" category.
```
### Getting Topic Details
You can ask for details about a specific Pest topic:
```
Show me the documentation for Pest installation.
```
```
Explain Pest expectations in detail.
```
```
I need help understanding Pest's arch testing system.
```
### Finding Code Examples
You can ask for code examples for a specific topic:
```
Show me examples of Pest test writing.
```
```
Give me code examples for Pest expectations.
```
```
How do I implement datasets in Pest? Show me some examples.
```
### Searching Documentation
You can search the Pest documentation for specific concepts:
```
Search Pest documentation for "mocking".
```
```
Find information about mutation testing in Pest.
```
```
What does Pest documentation say about test coverage?
```
### Combining with Coding Tasks
You can combine documentation queries with coding tasks:
```
I need to write tests for my PHP application using Pest. Show me the documentation and then help me implement it.
```
```
Help me create Pest tests for user authentication based on Pest documentation.
```
```
I'm working on a Laravel app. Show me the Pest documentation for testing and help me set up my test suite.
```
### Exploring Pest Features
You can explore Pest features by category:
```
What are the main testing features available in Pest?
```
```
Tell me about Pest's architecture testing capabilities.
```
```
What are the different ways to organize tests in Pest?
```
## Installation
### Augment Configuration
To use with Augment in Visual Studio Code:
1. Install the Augment extension from the VS Code marketplace if you haven't already.
2. Create a new directory for MCP servers if you don't have one already:
```bash
mkdir -p ~/.augment/mcp-servers
```
3. Clone this repository into that directory:
```bash
git clone https://github.com/your-username/pest-mcp-server.git ~/.augment/mcp-servers/pest-mcp-server
```
4. Install dependencies and build the server:
```bash
cd ~/.augment/mcp-servers/pest-mcp-server
npm install
npm run build
```
5. Configure Augment to use this MCP server by adding it to your Augment configuration:
Open VS Code settings (Cmd+, on Mac or Ctrl+, on Windows/Linux), search for "Augment", and find the "Augment: MCP Servers" setting. Click "Edit in settings.json" and add the following:
```json
"augment.mcpServers": {
"pest-server": {
"command": "node",
"args": ["~/.augment/mcp-servers/pest-mcp-server/build/index.js"]
}
}
```
Alternatively, you can use the absolute path to the server:
```json
"augment.mcpServers": {
"pest-server": {
"command": "node",
"args": ["/absolute/path/to/pest-mcp-server/build/index.js"]
}
}
```
6. Restart VS Code to apply the changes.
7. You can now use the Pest documentation tools with Augment in your PHP projects!
### Claude Desktop Configuration
To use with Claude Desktop, add the server config:
On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
#### Option 1: Using local build
```json
{
"mcpServers": {
"pest-server": {
"command": "/path/to/pest-mcp-server/build/index.js"
}
}
}
```
#### Option 2: Using npx command
```json
{
"mcpServers": {
"pest-server": {
"command": "npx",
"args": ["-y", "pest-mcp-server"]
}
}
}
```
### Windsurf Configuration
Add this to your `./codeium/windsurf/model_config.json`:
```json
{
"mcpServers": {
"pest-server": {
"command": "npx",
"args": ["-y", "pest-mcp-server"]
}
}
}
```
### Cursor Configuration
Add this to your `.cursor/mcp.json`:
```json
{
"mcpServers": {
"pest-server": {
"command": "npx",
"args": ["-y", "pest-mcp-server"]
}
}
}
```
### Debugging
Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:
```bash
npm run inspector
```
The Inspector will provide a URL to access debugging tools in your browser.
### Troubleshooting
If you encounter issues with the Pest MCP server, try these solutions:
1. **No Response from Server**:
- Make sure the server is properly installed and built
- Check that the path in your configuration is correct
- Try restarting VS Code
- Check the VS Code output panel for any error messages (View > Output, then select "Augment" from the dropdown)
2. **Server Crashes or Timeouts**:
- The server includes fallback data for common Pest topics, so it should still work even if it can't connect to GitHub
- If you're behind a corporate firewall or proxy, it might block GitHub API requests
- Try running the server manually to see any error output: `node /path/to/pest-mcp-server/build/index.js`
- The server caches documentation files locally, so it should work offline after the first successful run
3. **Incorrect or Missing Data**:
- The server caches data in memory for better performance. If you need fresh data, restart VS Code
- If specific topics are missing, you can manually add them to the fallback data in the source code
- To force a refresh of the cached documentation files, delete the `cache` directory and restart the server
4. **Augment Can't Find the Server**:
- Make sure the server name in your configuration matches exactly: `pest-server`
- Check that the path to the server is correct and accessible
- Try using an absolute path instead of `~` in your configuration
5. **Cache Issues**:
- The server stores documentation files in a `cache` directory next to the build directory
- If you're experiencing issues with cached files, you can delete the cache directory to force a fresh download
- Make sure the process running the server has write permissions to the cache directory
## Contributing
Contributions to improve the Pest MCP server are welcome! Here are some ways you can contribute:
1. **Bug Reports**: If you find a bug, please create an issue with detailed steps to reproduce it.
2. **Feature Requests**: If you have ideas for new features or improvements, please create an issue to discuss them.
3. **Documentation**: Help improve the documentation by fixing errors or adding examples.
4. **Code Contributions**: Submit pull requests for bug fixes or new features.
### Development Process
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Commit your changes (`git commit -m 'Add some amazing feature'`)
5. Push to the branch (`git push origin feature/amazing-feature`)
6. Open a Pull Request
### Keeping Up with Pest Documentation
This MCP server is designed to work with the latest Pest documentation. As Pest evolves, the server may need updates to support new versions or changes in the documentation structure.
## License
MIT
